[[77634]]

“你需要寫(xiě)更詳細(xì)的文檔”。你聽(tīng)到了沒(méi)有？我聽(tīng)到了，很多次，在很多公司里。大多數(shù)人都會(huì)因?yàn)闆](méi)有寫(xiě)文檔而內(nèi)心不安，認(rèn)為應(yīng)寫(xiě)文檔。但我不是。

文檔有兩種——代碼內(nèi)和代碼外。代碼內(nèi)文檔包括javadoc(或任何用來(lái)描述類(lèi)和類(lèi)方法的語(yǔ)言工具)和代碼注釋。外部文檔包括描述產(chǎn)品的文檔和內(nèi)部材料。

外部文檔***的問(wèn)題：它會(huì)過(guò)期不更新。讓它們保持同步更新是一個(gè)麻煩且耗時(shí)的工作。

外部文檔第二大問(wèn)題：沒(méi)有人真正用它們。

程 序員是寫(xiě)代碼的。他們善于讀代碼。代碼對(duì)于他們有特殊意義。給重要類(lèi)寫(xiě)說(shuō)明，在方法內(nèi)部對(duì)重要場(chǎng)景寫(xiě)注釋?zhuān)@被認(rèn)為是***編程實(shí)踐方法，優(yōu)秀的程序員都這 么做。這能讓代碼對(duì)于人們來(lái)說(shuō)更易理解，加上能自我說(shuō)明的編碼方法，這就是一部完整適用的文檔。它不需要你去同步更新(你修改代碼的同時(shí)修改了它)。

我們需要外部文檔嗎？也許吧。有必要對(duì)整個(gè)系統(tǒng)架構(gòu)做一些簡(jiǎn)潔的描述，讓這些代碼有一個(gè)大的背景。有哪些模塊，它們是如何交互的——這就夠了，只需一頁(yè)。但這同樣會(huì)過(guò)期不更新，但至少它比較容易維護(hù)，團(tuán)隊(duì)首領(lǐng)和架構(gòu)師需要經(jīng)常的檢查它們是否已經(jīng)過(guò)期。

如 果你是測(cè)試人員，或是產(chǎn)品經(jīng)理，你會(huì)說(shuō)你不理解這些程序，你的工作中需要這些文檔。我可能有些粗魯，但如果你需要這些東西，你應(yīng)該自己去寫(xiě)。程序員不是技 術(shù)文檔撰寫(xiě)員，寫(xiě)外部文檔不是他們的工作，也不是他們感興趣的。如果你不想寫(xiě)這些文檔，而你仍想知道這些程序是干什么的，那就去問(wèn)程序員吧。他們會(huì)樂(lè)意為 你讀這些注釋?zhuān)蚰憬忉屗鼈兊墓τ?。如果代碼的功用和期望的動(dòng)作不一致時(shí)，那去檢查問(wèn)題跟蹤系統(tǒng)，看看需求究竟是什么樣的。你不需要外部文檔來(lái)描述這些代 碼是干什么的。

當(dāng)然，軟件是給用戶使用的，需要一些用戶手冊(cè)，但這實(shí)際應(yīng)該由其他人來(lái)編寫(xiě)。

所以，下次當(dāng)有人堅(jiān)持認(rèn)為程序員需要寫(xiě)文檔來(lái)描述程序的功能時(shí)，駁斥他們。堅(jiān)信這是在浪費(fèi)時(shí)間和精力，堅(jiān)信有了代碼和注釋就足夠了。如果這些不夠，這說(shuō)明你需要有更好的編程規(guī)范和編程習(xí)慣，而不是寫(xiě)文檔。

原文鏈接：http://www.aqee.net/we-dont-need-that-documentation/

譯文鏈接：http://www.oschina.net/news/42377/wo-dont-need-document-but-code