我們不需要程式碼之外的文件

　　“你需要寫更詳細的文件”。你聽到了沒有？我聽到了，很多次，在很多公司裡。大多數人都會因為沒有寫文件而內心不安，認為應寫文件。但我不是。

　　文件有兩種——程式碼內和程式碼外。程式碼內文件包括javadoc(或任何用來描述類和類方法的語言工具)和程式碼註釋。外部文件包括描述產品的文件和內部材料。

　　外部文件最大的問題：它會過期不更新。讓它們保持同步更新是一個麻煩且耗時的工作。

　　外部文件第二大問題：沒有人真正用它們。

　　程式設計師是寫程式碼的。他們善於讀程式碼。程式碼對於他們有特殊意義。給重要類寫說明，在方法內部對重要場景寫註釋，這被認為是最佳程式設計實踐方法，優秀的程式設計師都這麼做。這能讓程式碼對於人們來說更易理解，加上能自我說明的編碼方法，這就是一部完整適用的文件。它不需要你去同步更新(你修改程式碼的同時修改了它)。

　　我們需要外部文件嗎？也許吧。有必要對整個系統架構做一些簡潔的描述，讓這些程式碼有一個大的背景。有哪些模組，它們是如何互動的——這就夠了，只需一頁。但這同樣會過期不更新，但至少它比較容易維護，團隊首領和架構師需要經常的檢查它們是否已經過期。

　　如果你是測試人員，或是產品經理，你會說你不理解這些程式，你的工作中需要這些文件。我可能有些粗魯，但如果你需要這些東西，你應該自己去寫。程式設計師不是技術文件撰寫員，寫外部文件不是他們的工作，也不是他們感興趣的。如果你不想寫這些文件，而你仍想知道這些程式是幹什麼的，那就去問程式設計師吧。他們會樂意為你讀這些註釋，向你解釋它們的功用。如果程式碼的功用和期望的動作不一致時，那去檢查問題跟蹤系統，看看需求究竟是什麼樣的。你不需要外部文件來描述這些程式碼是幹什麼的。

　　當然，軟體是給使用者使用的，需要一些使用者手冊，但這實際應該由其他人來編寫。

　　所以，下次當有人堅持認為程式設計師需要寫文件來描述程式的功能時，駁斥他們。堅信這是在浪費時間和精力，堅信有了程式碼和註釋就足夠了。如果這些不夠，這說明你需要有更好的程式設計規範和程式設計習慣，而不是寫文件。

　　英文原文：We Don’t Need That Documentation