人月神話-另外一面

最後一章仍然在講文檔和文檔有效性的問題。在開始就指出，我曾經非常勤奮地給我的軟體工程師們舉辦了多年關於文檔必要性以及優秀文檔所應具備特點方面的講座，向他們講述——甚至是熱誠地向他們勸誡以上的觀點。不過，這些都行不通。我想他們知道如何正確地編寫文檔，卻缺乏工作的熱情。所以這章重點仍然放在了如何寫文檔，文檔應該包含哪些核心要素上面。

不同使用者需要不同層級的文檔。某些使用者僅僅偶爾使用程式，有些使用者必須依賴程式，還有一些使用者必鬚根據環境和目的的變動對程式進行修改。在需要什麼樣的文檔一段從使用程式，驗證程式和修改程式三個方面來談如何寫文檔，文檔內容應該包含哪些核心要素。使用程式方面的文檔發生在程式編寫前，要描述清楚程式的目的，範圍，情境，輸入，輸出等各項重要內容。每一個發布的程式需要附加驗證說明，即準備我們常做的測試案例，這個發生在驗證測試階段。最後，調整程式或者修複程式需要更多的資訊。顯然，這要求瞭解全部的細節，並且這些細節已經記錄在注釋良好的列表中。

流程圖是被吹捧得最過分的一種程式文檔。事實上，很多程式甚至不需要流程圖，很少有程式需要一頁紙以上的流程圖。現實中，流程圖被鼓吹的程度遠大於它們的實際作用。我從來沒有看到過一個有經驗的編程人員，在開始編寫程式之前，會例行公事地繪製詳盡的流程圖。在一些要求流程圖的組織中，流程圖總是事後才補上。(在這裡我們需要重點強調的就是流程圖和各種形式化的表達方式更多應該是應用在構思和前期需求階段，真正到了設計開發階段的時候往往並不需要複雜完整的流程圖。)

最後談到了自文檔化程式，什麼意思呢？核心思想仍然是程式本身應該是可以自解釋的，詳細的可以看《原始碼即設計》一文。在這裡有兩個重要的階段，很多時候詳細設計可以省略掉，我們的重要設計思路會體現到我們的程式注釋中，再進一步很多垃圾無用的代碼注釋也要去掉，因為代碼寫好了，代碼本身應該具備自解釋能力。在原始碼編寫規範中談到的注釋，空行，縮排，變數命名，迴圈都有標準的編寫規範，如果我們還能多考慮代碼的複用和拆分，整個代碼檔案就能夠有很強的可讀性。