在實(shí)際的軟件開(kāi)發(fā)工作中，除了編寫(xiě)代碼之外，程序員還會(huì)花大量的時(shí)間來(lái)編寫(xiě)相關(guān)的研發(fā)文檔，這些文檔包括：詳細(xì)設(shè)計(jì)文檔、單元/集成/系統(tǒng)測(cè)試文檔、軟件版本開(kāi)發(fā)報(bào)告、軟件安裝說(shuō)明、軟件升級(jí)指導(dǎo)書(shū)、軟件使用手冊(cè)等。我認(rèn)為：“代碼”和“文檔”就像是一個(gè)人的左膀右臂，一定要讓兩者均衡發(fā)展，而不能夠只顧其一。既然文檔這么的重要，那么對(duì)于程序員來(lái)說(shuō)，我們?nèi)绾尾拍軐?xiě)出一份好的文檔呢?

[[215533]]

根據(jù)我個(gè)人的經(jīng)驗(yàn)，我們不妨從以下方面入手：

***，將重要的內(nèi)容分點(diǎn)描述，而不是雜糅在一起。

例如，有一段描述某軟件功能的話是這樣的：

該軟件模塊在系統(tǒng)中占有重要的地位，它從客戶提供的FTP目錄下獲取文件，并下載到本地的目錄中。接著，它掃描本地目錄，對(duì)讀取到的文件的內(nèi)容進(jìn)行解析，并生成新的文件放到本地的另一目錄中。然后，它將該目錄中的文件上傳到客戶指定的FTP目錄中。對(duì)于本地目錄中的文件，該模塊有一個(gè)過(guò)期清理的機(jī)制，清理時(shí)間及過(guò)期期限可配置。

我們可以看到，上面那段話將軟件功能描述放到一個(gè)段落中，讀起來(lái)讓讀者云里霧里的。

我們可以把內(nèi)容分點(diǎn)描述，如下：

1. 該軟件模塊在系統(tǒng)中占有重要的地位，其實(shí)現(xiàn)的主要功能為：
2. 從客戶提供的FTP目錄中下載文件到本地的目錄中。
3. 從本地目錄中獲取文件進(jìn)行解析，并生成新的文件放到本地的另一目錄中。
4. 將目錄中生成的文件上傳到客戶指定的FTP目錄中。
5. 清理本地目錄中的過(guò)期文件(清理時(shí)間及過(guò)期期限可配置)。

這樣修改之后，文章的邏輯更加的清晰，可讀性更強(qiáng)，讀者也更容易理解作者所要表達(dá)的意思。

第二，將流程性比較強(qiáng)的內(nèi)容畫(huà)成流程圖，而不是僅用文字描述。

一篇圖文并茂的文章才是好文章，如果大家看到一篇好幾十頁(yè)的文章全是文字，很容易失去閱讀的興趣。對(duì)于某些流程性比較強(qiáng)的內(nèi)容，如果將文字變成流程圖，則給讀者的感覺(jué)是不一樣的。

例如，下面一段文字描述了socket的整個(gè)消息流程：

• ***步，創(chuàng)建socket。
• 第二步，綁定指定的IP地址和端口。如果綁定失敗，則跳到***步。
• 第三步，啟動(dòng)監(jiān)聽(tīng)。如果沒(méi)有監(jiān)聽(tīng)到消息，則程序一直處于監(jiān)聽(tīng)狀態(tài);如果監(jiān)聽(tīng)到了消息，則執(zhí)行下一步。
• 第四步，循環(huán)從監(jiān)聽(tīng)隊(duì)列中獲取消息，并根據(jù)消息內(nèi)容執(zhí)行相關(guān)的操作。

將文字內(nèi)容畫(huà)成流程圖，如下所示：

從流程圖中，我們更容易看出程序的邏輯，讓讀者在一段輕松的閱讀旅程中理解作者所要表達(dá)的意思。

第三，將帶數(shù)字的內(nèi)容以圖表的形式呈現(xiàn)，而非用文字描述。

對(duì)于某些有參照性質(zhì)的數(shù)字，我們可以用圖表的形式來(lái)呈現(xiàn)，這樣可以讓讀者看到相鄰幾組數(shù)字的變化情況，文章的表達(dá)效果更好。

例如，有下面一段描述：

今年3月份，解決的軟件bug數(shù)量為8;今年4月份，解決的軟件bug數(shù)量為6;今年5月份，解決的軟件bug數(shù)量為10。

可以將以上內(nèi)容替換成下面的圖表：

從圖中，我們更容易看出前后數(shù)字的變化情況，對(duì)所描述事物有一個(gè)整體的把握。

第四，盡量不要直接在文檔中貼代碼，而換之以偽代碼、流程圖等形式。

也許是為了省事，很多程序員喜歡將工程代碼直接粘貼到文檔中，這不僅會(huì)占用大量的文檔篇幅，而且會(huì)降低文檔的可讀性。試想，一個(gè)從沒(méi)有接觸過(guò)代碼的人，如何能夠看懂你在文檔中給出的代碼?即使對(duì)于有經(jīng)驗(yàn)的程序員來(lái)說(shuō)，一眼看到你寫(xiě)出來(lái)的程序，也不見(jiàn)得能夠一下就明白的。

如果你寫(xiě)的代碼確實(shí)很好，想給別人看，那么在正文中可以只給出設(shè)計(jì)思想、流程圖等，而在附錄中給出完整的代碼。

以上幾點(diǎn)寫(xiě)文檔的建議是本人在寫(xiě)文檔過(guò)程中的一些心得體會(huì)，不見(jiàn)得都正確，大家可以參考?？偟恼f(shuō)來(lái)，文檔的編寫(xiě)要遵循簡(jiǎn)單易懂的原則，要用最直接明了的方式來(lái)表達(dá)作者本人的意思。

愛(ài)因斯坦曾說(shuō)過(guò)：“科學(xué)家應(yīng)該使用最簡(jiǎn)單的手段達(dá)到他們的結(jié)論，并排除一切不能被認(rèn)識(shí)到的事物”。也就是說(shuō)，簡(jiǎn)單就是美。這個(gè)“簡(jiǎn)單”的原則同樣可以應(yīng)用到文檔編寫(xiě)中，應(yīng)用到所有的軟件開(kāi)發(fā)項(xiàng)目中。

【本文是51CTO專欄作者周兆熊的原創(chuàng)文章，作者微信公眾號(hào)：周氏邏輯(logiczhou)】

戳這里，看該作者更多好文