程序員要面對的不僅是代碼，還有文檔
在實際的軟件開發工作中，除了編寫代碼之外，程序員還會花大量的時間來編寫相關的研發文檔，這些文檔包括：詳細設計文檔、單元/集成/系統測試文檔、軟件版本開發報告、軟件安裝說明、軟件升級指導書、軟件使用手冊等。我認為：“代碼”和“文檔”就像是一個人的左膀右臂，一定要讓兩者均衡發展，而不能夠只顧其一。既然文檔這么的重要，那么對于程序員來說，我們如何才能寫出一份好的文檔呢?
根據我個人的經驗，我們不妨從以下方面入手：
***，將重要的內容分點描述，而不是雜糅在一起。
例如，有一段描述某軟件功能的話是這樣的：
該軟件模塊在系統中占有重要的地位，它從客戶提供的FTP目錄下獲取文件，并下載到本地的目錄中。接著，它掃描本地目錄，對讀取到的文件的內容進行解析，并生成新的文件放到本地的另一目錄中。然后，它將該目錄中的文件上傳到客戶指定的FTP目錄中。對于本地目錄中的文件，該模塊有一個過期清理的機制，清理時間及過期期限可配置。
我們可以看到，上面那段話將軟件功能描述放到一個段落中，讀起來讓讀者云里霧里的。
我們可以把內容分點描述，如下：
- 該軟件模塊在系統中占有重要的地位，其實現的主要功能為：
- 從客戶提供的FTP目錄中下載文件到本地的目錄中。
- 從本地目錄中獲取文件進行解析，并生成新的文件放到本地的另一目錄中。
- 將目錄中生成的文件上傳到客戶指定的FTP目錄中。
- 清理本地目錄中的過期文件(清理時間及過期期限可配置)。
這樣修改之后，文章的邏輯更加的清晰，可讀性更強，讀者也更容易理解作者所要表達的意思。
第二，將流程性比較強的內容畫成流程圖，而不是僅用文字描述。
一篇圖文并茂的文章才是好文章，如果大家看到一篇好幾十頁的文章全是文字，很容易失去閱讀的興趣。對于某些流程性比較強的內容，如果將文字變成流程圖，則給讀者的感覺是不一樣的。
例如，下面一段文字描述了socket的整個消息流程：
- ***步，創建socket。
- 第二步，綁定指定的IP地址和端口。如果綁定失敗，則跳到***步。
- 第三步，啟動監聽。如果沒有監聽到消息，則程序一直處于監聽狀態;如果監聽到了消息，則執行下一步。
- 第四步，循環從監聽隊列中獲取消息，并根據消息內容執行相關的操作。
將文字內容畫成流程圖，如下所示：
從流程圖中，我們更容易看出程序的邏輯，讓讀者在一段輕松的閱讀旅程中理解作者所要表達的意思。
第三，將帶數字的內容以圖表的形式呈現，而非用文字描述。
對于某些有參照性質的數字，我們可以用圖表的形式來呈現，這樣可以讓讀者看到相鄰幾組數字的變化情況，文章的表達效果更好。
例如，有下面一段描述：
今年3月份，解決的軟件bug數量為8;今年4月份，解決的軟件bug數量為6;今年5月份，解決的軟件bug數量為10。
可以將以上內容替換成下面的圖表：
從圖中，我們更容易看出前后數字的變化情況，對所描述事物有一個整體的把握。
第四，盡量不要直接在文檔中貼代碼，而換之以偽代碼、流程圖等形式。
也許是為了省事，很多程序員喜歡將工程代碼直接粘貼到文檔中，這不僅會占用大量的文檔篇幅，而且會降低文檔的可讀性。試想，一個從沒有接觸過代碼的人，如何能夠看懂你在文檔中給出的代碼?即使對于有經驗的程序員來說，一眼看到你寫出來的程序，也不見得能夠一下就明白的。
如果你寫的代碼確實很好，想給別人看，那么在正文中可以只給出設計思想、流程圖等，而在附錄中給出完整的代碼。
以上幾點寫文檔的建議是本人在寫文檔過程中的一些心得體會，不見得都正確，大家可以參考?？偟恼f來，文檔的編寫要遵循簡單易懂的原則，要用最直接明了的方式來表達作者本人的意思。
愛因斯坦曾說過：“科學家應該使用最簡單的手段達到他們的結論，并排除一切不能被認識到的事物”。也就是說，簡單就是美。這個“簡單”的原則同樣可以應用到文檔編寫中，應用到所有的軟件開發項目中。
【本文是51CTO專欄作者周兆熊的原創文章，作者微信公眾號：周氏邏輯(logiczhou)】
