你為程序編寫文檔嗎？為什麼？

01-04

得@梁濤邀請。抱歉來遲。

其實老莊上面的回答最符合我的想法。不過我覺得稍微有些簡單了。我補充一些細節吧。

首先，文檔一般分狹義的文檔包括哪些組成部分？一般有三：設計說明，API手冊，以及其他支持文檔，包括使用和配置手冊等等。

第二，廣義的文檔包括哪些？它包括所有的狹義文檔，以及代碼。

那麼，哪些部分需要文檔化？一般我的原則是：

設計說明是必須有的。包括架構、技術選型、環境限制、關鍵演算法（特別是演算法密集型程序）
支持文檔是必須有的。具體地包括：編譯步驟（如果有編譯的需要），安裝和快速上手，常見問題以及用於反映問題時的內部郵件列表。
API文檔要分開討論。如果是外部API，那麼是應該把所有的參數、返回值和行為都文檔化。如果是內部函數，則一般不推薦文檔化。

文檔化的形式我認為不重要，有人喜歡Wiki，有人喜歡Word文檔，看項目需要都可以，只要能滿足基本的可搜索和可讀性要求。但是內容不能少。

這裡可能要解釋一下為什麼說內部函數不推薦文檔化。因為內部函數本身是常變的，同時維護文檔和代碼只會加大工作量，而一旦代碼和文檔不同步，則反而影響閱讀。好的代碼應該保證基本的可讀性。除了一種例外，很不幸地也是現在Windows上很常見的一種例外，就是當你的程序大量應用非同步/回調模型時，最好把那些回調函數的主調/被調關係文檔化，即便它們是內部API。

為什麼要強調這個例外？因為非同步/回調函數的代碼的調用鏈並不連續，至少和調用棧不匹配，這種情況下可讀性都相對較差。無論我們把函數和參數命名寫得再好都難以彌補。對不熟悉代碼的人來說，僅僅看代碼，他們可能連調用次序都說不清楚。所以此類函數應該也屬於永遠需要文檔化的。

我不為程序本身編寫文檔。但時常要為客戶、項目和軟體寫文檔。

PS:有人很不待見寫文檔，這些人多半是不會寫文檔。

我12年來所見，能把文檔的結構規劃清晰、把文字寫流暢、把問題表達清楚的人，很少。

我來簡要分析一下不寫文檔的心態：

1。臨時用的程序，不寫。因為寫完用完基本就人扔了。

2。原型程序，不寫，因為這常常僅僅是為了給人演示功能的可行性以及用來深度挖掘需求的工具，項目如果正式做了，整個架構都要推重，肯定希望重新設計該程序的時候再來寫文檔。

3。自己對自己的項目沒有信心的，或者自己覺得自己對這個項目貢獻的部分屬於無關緊要的部分，不寫，這可能也是很多人的狀態，因為覺得這個項目根本不可能延續很長的時間，而且自己的工作是次要工作，有沒有文檔也不是什麼大不了的事情，這種心態造就了廣大的碼農團體。

4。想要通過保密創造技術壁壘的，不寫，有些人認為自己的程序最好是沒人看懂，只有這樣，自己才是這個團隊不可缺少的。

但我覺得，文檔必寫：

1。語言本身有基於語言框架自動生成文檔框架體系的，必寫文檔。

2。中等以上的項目若從零開始，必寫，否則對整個項目的架構掌控將很抓狂。

3。自己有信心的項目，必寫，因為一個優秀的程序將持續的時間以及將被移植到的平台都會遠遠超過最初的預期。

偶爾寫。一直很想寫，但是一直很少寫。就算寫了也很不滿意，總覺得掛一漏萬。

因為寫文檔可比寫代碼難多了。現實需求，設計思路，框架結構，一些trick…… 總想把東西都寫進去，但卻不可能都寫進去。寫了還要注意可讀性，是否易於理解，是否易於翻閱和查詢。經常寫到一半，突然覺得換另一個角度能更好地說明問題。

從代碼和注釋中自動生成的文檔，基本上不能滿足我的要求。我很難從這些文檔中把握設計思路，至於具體介面和實現過程，看文檔不如直接看代碼。

有時候想設計一種能自由組織的文檔系統。所有的內容都存在於一個個獨立節點之內。然後根據不同的視圖/角度/邏輯或者別的什麼說法，能自行組合出一個閱讀順序出來。比如說這個系統，我們從業務功能角度縱切來看分這麼幾塊，分別是xxxxxxx, 然後換一個角度橫切來看又分幾層，每層分別是xxxxxx，內容都是這麼些內容，卻有不同的組織形式。

看情況了，如果自己做的小玩意，多寫點注釋，外加一個txt的提綱列表和TODO列表即可。

如果是和他人合作，還是得寫的，每次寫的不一樣，分人、分項目。

當然寫啊。

文檔裡面寫，注釋裡面也要把比較敏感的東西說的一清二楚，恨不得舉個例子。

寫的這麼清楚，方便別人，也方便自己將來維護。

不寫文檔，代碼又讓人看不懂的項目，沒人願意接手。

我覺得文檔是必須要的，有些東西代碼體現不出來；

代碼也是要寫好看的，代碼是給人看的，給機器執行的，人不能看的代碼不叫代碼；

兩者是互為補充，幫助人理解。

因為理解代碼的時間超過了寫文檔的時間而寫。

因為代碼的價值不如寫文檔的時間而不寫。

拒絕自動文檔生成工具。每個函數都有文檔的文檔如同沒有文檔。沒有文檔也是一種信息。

為過程寫文檔，不如為數據結構寫文檔。

文檔問題，是全宇宙程序員的一個老大難問題了，一個通病

幾乎人人都認為應該寫，可是真正寫的人卻很少

而也正是這少數人，最後成長為了專家，其他的就成了所謂的碼農

寫是為了讓你的代碼流傳的更遠，活得更久

不寫只是為了偷懶，最自己不負責，也對別人不負責

順便推薦一個文檔乖哦國內劇，doxygen

可以減少工作量，最後形成的文檔也比較規範

這個文檔的範疇就廣了。

從需求到設計到說明到API再到協議等等這些都是文檔的範疇，單說需不需要給程序寫文檔，這個很難界定的。

我覺得，像需求文檔、API文檔以及協議文檔，這些是要生成的。因為這些文檔涉及到甲方乙方以及第三方，如果沒有文檔進行約束，最終的結果只是大家相互扯嘴皮，所以我覺得這些文檔是必須的。

但是像概設、詳設這些文檔的話，我覺得可以側重於工程的整體架構、模塊的結構和設計思路以及關鍵點等，沒必要還要按照老的模版寫得那麼具體，冗長，耗時耗力，而且現在客戶的需求是一直在變的，文檔太具體了，就會隨著需求的變動而變動，這樣，不光要維護代碼，還要維護文檔，對於一個小團隊，這個成本不小，而且也會帶來一定風險，比如，代碼和文檔不一致。

所以，我的觀點是，文檔這東西，關鍵作用還是約束，在這個前提下生成文檔，還是很有必要的。設計文檔，是約束內部的，保證整體架構，模塊之間通信的一致性和可維護性。需求文檔、API文檔、協議文檔，是約束外部的，保證工程可控，操作說明嘛，就是用來約束用戶的了~

沒有文檔就寫代碼，就跟沒有設計圖就施工一樣。有多少人會住這樣建出來的房子，就有多少客戶會用這樣寫出來的程序。

如果代碼寫的足夠漂亮（命名規範、邏輯清晰、配合適當的注釋），那麼文檔可以寫的簡單些，我認為只需要一些綱領性的東西就足夠了。可是大部分人的代碼寫的不夠漂亮，所以還是老老實實、認認真真地寫好文檔吧。

不寫設計文檔，但是會去寫用戶手冊和實現流程檔備查

設計方案+代碼文檔化

以前老師說，最好的文檔就是注釋。

注釋寫得明白，文檔就不必了。

感覺就是操作手冊，用的時候再看，如果代碼命名不好，還是要看操作手冊。

我用wiz，直接做成日記

文檔一定要寫啦. 代碼注釋也要寫, 現在是一個多核時代. 所以特別要寫明一些關於線程安全, 或者會影響安全, 性能, 穩定該注意的地方. 對於第三方開發修改, 要寫好自己的架構, 和擴展點, 舉一些例子等.

通用組件，框架類程序會寫使用指南之類的文檔，方便使用也方便日後查閱。業務邏輯代碼不寫文檔，因為業務邏輯經常變化且本身比較容易看懂，直接看代碼即可。