讓你提前認識軟體開發(40)：既要寫好代碼，又要寫好文檔

標籤：style   blog   http   color   strong   資料   2014   問題   

第3部分 軟體研發工作總結

既要寫好代碼，又要寫好文檔

 

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

        工作也有一段時間了，我發現周圍的同事，會寫高品質文檔的確實很少。李開複老師在《浪潮之巔》的序言中說到：“我認識很多頂尖的工程師，但具備強大敘事能力的優秀工程師，我認識的可以說是鳳毛麟角。”確實，我所認識的同事，能夠清晰表達自己思想的人也很少。

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

        (1) 我們每天都會收發很多郵件，我仔細看了一下，很多郵件裡面的內容要麼語句不通順、要麼有很多錯別字、要麼誤用或沒有標點符號。很多時候，從不同的角度理解，一封郵件有很多不同的意思，讓人感覺不知道它究竟要表達一個什麼意思，這樣極大地降低了工作的效率。

        (2) 除了代碼之外，項目也會包含了大量的文檔。開啟大部分文檔，看到的第一眼，我就有這幾種感覺：排版不工整、格式不正確、語句不通順、錯別字連篇。一看就知道作者沒有認真寫文檔，並且語句的表達和組織能力也不強。

        (3) 在項目小組成員討論的時候，大家幾乎都在說怎樣把程式寫好，而沒有提到在文檔書寫方面應如何努力去改進。大家一直認為開發人員的職責就是把程式寫好，其它什麼的都是其次的。

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

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

圖1 軟體開發不同階段涉及到的主要文檔

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

 

       在軟體產品相關文檔中，詳細設計文檔是非常重要的。通過對設計思路的詳細描述，不但可以為本模組的編碼工作提供必要的基礎，還可以為測試人員提供一定的參考。

        一般說來，一份完整的詳細設計文檔的主體內容要包括2所示的9個部分。

圖2 一份完整的詳細設計文檔的主體內容

 

        整合測試方案(規程)文檔用於指導軟體的整合測試工作，也是一類很重要的文檔。

        一般說來，一份完整的整合測試方案(規程)文檔的主體內容要包括3所示的6個部分。

圖3 一份完整的整合測試方案(規程)文檔的主體內容

 

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

        那麼，我們如何才能寫出高品質的文檔呢？我認為可以從如下幾個方面著手：

        (1) 改變文檔為輔的觀念，在平常的工作中，對於自己編寫的每一份文檔，均認真對待。

        (2) 對於郵件的編寫，要把自己想說的話準確地表達出來，在發送郵件之前，再看一下內容是否完整、是否還有錯別字、語句是否通順等。

        (3)在編寫文檔的過程中，要嚴格參照項目組規定的模板來完成。在寫完文檔之後，對文檔進行語法檢查，以糾正錯別字和有語法錯誤的地方。一般說來，有語法錯誤的語句下面會有一條綠色的波浪線。在提交文檔之前，再通讀一下整個文檔，看是否還有疏漏和不足。

        (4) 在工作之餘，可以讀一些能夠提高語言表達能力和寫作能力的書籍，看一下別人是怎麼表達自己思想的。在此，推薦閱讀吳軍的《浪潮之巔》(http://book.douban.com/subject/24738302/)、《數學之美》(http://book.douban.com/subject/10750155/)和《文明之光》(http://book.douban.com/subject/25902942/)，以及劉未鵬的《暗時間》(http://book.douban.com/subject/6709809/)，這幾本書寫得都比較好。

 

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

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

 

 

 

 

(本人微博：http://weibo.com/zhouzxi?topnav=1&wvr=5，號：245924426，歡迎關注！)