建站
咨詢
售后
建站咨詢
新聞中心
“你需要寫更詳細的文檔”。你聽到了沒有？我聽到了，很多次，在很多公司里。大多數(shù)人都會因為沒有寫文檔而內(nèi)心不安，認為應(yīng)寫文檔。但我不是。
文檔有兩種——代碼內(nèi)和代碼外。代碼內(nèi)文檔包括javadoc(或任何用來描述類和類方法的語言工具)和代碼注釋。外部文檔包括描述產(chǎn)品的文檔和內(nèi)部材料。
外部文檔***的問題：它會過期不更新。讓它們保持同步更新是一個麻煩且耗時的工作。
外部文檔第二大問題：沒有人真正用它們。
程 序員是寫代碼的。他們善于讀代碼。代碼對于他們有特殊意義。給重要類寫說明，在方法內(nèi)部對重要場景寫注釋，這被認為是***編程實踐方法，優(yōu)秀的程序員都這 么做。這能讓代碼對于人們來說更易理解，加上能自我說明的編碼方法，這就是一部完整適用的文檔。它不需要你去同步更新(你修改代碼的同時修改了它)。
我們需要外部文檔嗎？也許吧。有必要對整個系統(tǒng)架構(gòu)做一些簡潔的描述，讓這些代碼有一個大的背景。有哪些模塊，它們是如何交互的——這就夠了，只需一頁。但這同樣會過期不更新，但至少它比較容易維護，團隊首領(lǐng)和架構(gòu)師需要經(jīng)常的檢查它們是否已經(jīng)過期。
如 果你是測試人員，或是產(chǎn)品經(jīng)理，你會說你不理解這些程序，你的工作中需要這些文檔。我可能有些粗魯，但如果你需要這些東西，你應(yīng)該自己去寫。程序員不是技 術(shù)文檔撰寫員，寫外部文檔不是他們的工作，也不是他們感興趣的。如果你不想寫這些文檔，而你仍想知道這些程序是干什么的，那就去問程序員吧。他們會樂意為 你讀這些注釋，向你解釋它們的功用。如果代碼的功用和期望的動作不一致時，那去檢查問題跟蹤系統(tǒng)，看看需求究竟是什么樣的。你不需要外部文檔來描述這些代 碼是干什么的。
當然，軟件是給用戶使用的，需要一些用戶手冊，但這實際應(yīng)該由其他人來編寫。
所以，下次當有人堅持認為程序員需要寫文檔來描述程序的功能時，駁斥他們。堅信這是在浪費時間和精力，堅信有了代碼和注釋就足夠了。如果這些不夠，這說明你需要有更好的編程規(guī)范和編程習慣，而不是寫文檔。
當前名稱：我們不需要代碼之外的文檔
文章鏈接：http://www.5511xx.com/article/djpijjg.html
