程式設計師既要寫好程式碼，又要寫好文件

作為一個長期混跡於CSDN社群的人，我對很多擁有高訪問量的博主欽佩不已，特別是在參加了CSDN在舉辦“2014 CSDN博文大賽”及“2015 CSDN-Markdown博文大賽”活動之後。我看到活動中的一些參賽作品條理清晰、文筆流暢、語言優美，大都出自程式設計師之手。我不禁想到一個問題：程式設計師是否應該注重文件的編寫？

寫文件的重要性

對於軟體相關行業，在學校或單位大家也許都已經注意到了，除了要編寫的程式、繪製設計圖之外，還有一個重要的工作便是寫文件。為什麼要寫文件呢？因為我們要把自己做的東西展示出來，不光展示給同行看，可能還要展示給其他崗位上的工作人員看，甚至展示給使用者看。如果我們只是會寫程式，不會在文件中恰當且優雅地描述自己的想法，那麼就真正的成為“碼農”了。

我注意了一下，周圍的同事會寫高質量文件的確實很少。李開復老師在《浪潮之巔》的序言中說到：“我認識很多頂尖的工程師，但具備強大敘事能力的優秀工程師，我認識的可以說是鳳毛麟角。”確實，我所認識的同事，能夠在文件中清晰地表達自己想法的也很少。

有關文件書寫，我印象很深的問題有如下幾個方面：

1.我們每天都會收發很多郵件，我仔細看了一下，很多郵件裡面的內容要麼語句不通順、要麼有很多錯別字、要麼誤用或沒有標點符號。很多時候，從不同的角度理解，一封郵件有很多不同的意思，讓人感覺不知道它究竟要表達一個什麼意思，這樣極大地降低了工作的效率。
2.除了程式碼之外，專案也會包含了大量的文件。開啟大部分文件，看到的第一眼，我就有這幾種感覺：排版不工整、格式不正確、語句不通順、錯別字連篇。一看就知道作者沒有認真寫文件，並且語句的表達和組織能力也不強。
3.在專案小組成員討論的時候，大家幾乎都在說怎樣把程式寫好，而沒有提到在文件書寫方面應如何努力去改進。大家似乎一致認為開發人員的職責就是把程式寫好，其它什麼的都是其次的。

有關計算機軟體的傳統定義為：軟體是計算機系統中與硬體相依存的另一部分，軟體包括程式、資料及其相關文件的完整集合。注意，這裡面就提到了“相關文件”，如果文件沒有寫好，那麼軟體也不能算是優秀的軟體。事實上，軟體功能健全，而由於文件原因出現故障的情況還時有發生。

一般說來，在軟體開發過程中，不同階段涉及到的主要文件如下圖所示：

可見，在軟體的不同階段，需要編寫不同的文件。在計劃階段，需要編寫詳細設計文件、單元測試方案文件和整合測試方案文件等；在開發階段，也是這幾個文件，不過是修訂版，因為我們在實際開發過程中，會發現之前設計不合理的地方或者是考慮不周的地方，這就需要對之前的文件進行修改；在測試階段，要編寫單元測試報告、整合測試報告和系統測試報告等；在軟體的釋出階段，要編寫安裝手冊、使用者手冊、升級指導書等，這些文件主要是面向現場支援人員和使用者的，因此要儘量寫得通俗易懂，千萬不要有模稜兩可的情況存在，否則就只有等待使用者的投訴了。

要想寫好文件，我們需要首先糾正一個觀念：文件不重要。要把文件放在與程式同等重要的位置。

程式設計師如何寫出高質量文件？

既然文件這麼的重要，那麼對於程式設計師來說，我們如何才能寫出一份好的文件呢？根據我個人的經驗，我們不妨從以下方面入手：

第一，將重要的內容分點描述，而不是雜糅在一起。

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

該軟體模組在系統中佔有重要的地位，它從客戶提供的FTP目錄下獲取檔案，並下載到本地的目錄中。接著，它掃描本地目錄，對讀取到的檔案的內容進行解析，並生成新的檔案放到本地的另一目錄中。然後，它將該目錄中的檔案上傳到客戶指定的FTP目錄中。對於本地目錄中的檔案，該模組有一個過期清理的機制，清理時間及過期期限可配置。

我們可以看到，上面那段話將軟體功能描述放到一個段落中，讀起來讓讀者雲裡霧裡的。我們可以把內容分點描述，如下：

該軟體模組在系統中佔有重要的地位，其實現的主要功能為：
(1)從客戶提供的FTP目錄中下載檔案到本地的目錄中。
(2)從本地目錄中獲取檔案進行解析，並生成新的檔案放到本地的另一目錄中。
(3)將目錄中生成的檔案上傳到客戶指定的FTP目錄中。
(4)清理本地目錄中的過期檔案(清理時間及過期期限可配置)。

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

第二，將流程性比較強的內容畫成流程圖，而不是僅用文字描述。

一篇圖文並茂的文章才是好文章，如果大家看到一篇好幾十頁的文章全是文字，很容易失去閱讀的興趣。對於某些流程性比較強的內容，如果將文字變成流程圖，則給讀者的感覺是不一樣的。

例如，下面一段文字描述了socket的整個訊息流程：

第一步，建立socket。
第二步，繫結指定的IP地址和埠。如果繫結失敗，則跳到第一步。
第三步，啟動監聽。如果沒有監聽到訊息，則程式一直處於監聽狀態；如果監聽到了訊息，則執行下一步。
第四步，迴圈從監聽佇列中獲取訊息，並根據訊息內容執行相關的操作。

將文字內容畫成流程圖，如下所示：

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

第三，將帶數字的內容以圖表的形式呈現，而非用文字描述。

對於某些有參照性質的數字，我們可以用圖表的形式來呈現，這樣可以讓讀者看到相鄰幾組數字的變化情況，文章的表達效果更好。

例如，有下面一段描述：

今年3月份，解決的軟體bug數量為8；今年4月份，解決的軟體bug數量為6；今年5月份，解決的軟體bug數量為10。

可以將以上內容替換成下面的圖表：

從圖中，我們更容易看出前後數字的變化情況，對所描述事物有一個整體的把握。

第四，儘量不要直接在文件中貼程式碼，而換之以虛擬碼、流程圖等形式。

也許是為了省事，很多程式設計師喜歡將工程程式碼直接貼上到文件中，這不僅會佔用大量的文件篇幅，而且會降低文件的可讀性。試想，一個從沒有接觸過程式碼的人，如何能夠看懂你在文件中給出的程式碼？即使對於有經驗的程式設計師來說，一眼看到你寫出來的程式，也不見得能夠一下就明白的。如果你寫的程式碼確實很好，想給別人看，那麼在正文中可以只給出設計思想、流程圖等，而在附錄中給出完整的程式碼。

以上幾點寫文件的建議是本人在寫文件過程中的一些心得體會，不見得都正確，大家可以參考。總的說來，文件的編寫要遵循簡單易懂的原則，要用最直接明瞭的方式來表達作者本人的意思。

愛因斯坦曾說過：“科學家應該使用最簡單的手段達到他們的結論，並排除一切不能被認識到的事物”。也就是說，簡單就是美。這個“簡單”的原則同樣可以應用到文件編寫中，應用到所有的軟體開發專案中。

其它一些建議

1.改變文件為輔的觀念，在平常的工作中，對於自己編寫的每一份文件，均認真對待。
2.對於郵件的編寫，要把自己想說的話準確地表達出來，在傳送郵件之前，再看一下內容是否完整、是否還有錯別字、語句是否通順等。
3.在編寫文件的過程中，要嚴格參照專案組規定的模板來完成。在寫完文件之後，對文件進行語法檢查，以糾正錯別字和有語法錯誤的地方。一般說來，有語法錯誤的語句下面會有一條綠色的波浪線。在提交文件之前，再通讀一下整個文件，看是否還有疏漏和不足。
4.在工作之餘，可以讀一些能夠提高語言表達能力和寫作能力的書籍或文章，看一下別人是怎樣清晰地闡述自己思想的。例如，經常閱讀CSDN上面優秀博主的博文就是一個提高自己寫作能力的好辦法。

總結

總的說來，和做其它事情一樣，書寫文件也反映了一個人的態度問題。寫出高質量的文件，不僅可以提升個人的形象（如果你看到一篇好文件，是不是也對作者有較高的評價？），還能夠提升產品在客戶心中的形象。如此分析，多花些心思來書寫文件真的是很有必要。

要想做好一件事情，需要我們從各個方面來努力。在開發軟體的過程中，寫好程式碼很重要，清楚明瞭地在文件中表達自己思想同樣非常的重要。“程式碼”和“文件”就像是一個人的左膀右臂，一定要讓兩者均衡發展，而不能夠只顧其一。