軟體的另一張臉#
每一個程式都有兩個面向、兩類讀者：
- 機器——執行程式的硬體
- 人類——使用和維護程式的使用者與開發者
大多數程式設計師把全部心力放在第一個面向：讓程式正確運行。但 Brooks 認為，第二個面向——文件（documentation）——同樣重要，甚至在軟體的整個生命週期中更為關鍵。
一個沒有文件的程式，對使用者而言幾乎不存在。即便功能完備，如果沒有人知道如何使用它，它的價值就是零。
給使用者的文件#
Brooks 列出了使用者文件必須包含的九大要素：
- 目的（Purpose）：這個程式做什麼？解決什麼問題？
- 環境（Environment）：需要什麼硬體、作業系統、設定？
- 領域與範圍（Domain and Range）：合法的輸入是什麼？可能的輸出是什麼？
- 實現的功能（Functions Realized）：提供哪些功能？
- 輸入/輸出格式（Input/Output Formats）：確切的語法和資料格式
- 操作說明（Operating Instructions）：如何啟動、執行、終止？
- 選項（Options）：有哪些開關和參數可以調整？
- 執行時間（Running Time）：處理不同規模的輸入需要多久？
- 精確度與容差（Accuracy and Tolerance）：結果的精確程度如何？
這九大要素不需要冗長的篇幅。對於小型程式，每個要素可能只需要一兩句話。關鍵是不遺漏——使用者在嘗試使用程式時，最常遇到的挫折就是某個關鍵資訊沒有被記錄下來。
給維護者的文件#
當未來的開發者需要修改程式時，他們需要的資訊與使用者截然不同：
- 結構圖（structure graph）：各元件之間如何連接的全域概觀
- 演算法說明（algorithms）：關鍵邏輯的設計原理與選擇理由
- 檔案與資料佈局（file/data layouts）：內部資料結構的格式與意義
- 處理流程（pass structure）：在多階段系統中，資料如何從一個階段流向下一個階段
其中，結構圖是最有價值的。一張清楚的全域結構圖，比數十頁的文字描述更能幫助維護者理解系統的全貌。
流程圖的迷思#
在 Brooks 的時代，流程圖（flowchart）被視為程式文件的核心。Brooks 對此提出尖銳的批評：
流程圖被嚴重高估了。
一張單頁的結構圖，顯示模組之間的關係，遠比多頁的詳細流程圖更為實用。詳細的流程圖試圖以圖形方式重述程式碼已經表達的邏輯——這不僅是冗餘的，而且維護成本極高。
Brooks 的結論是：原始碼本身就是最詳細的流程圖。 任何試圖在原始碼之外維護一份等量資訊的文件，都注定會與原始碼脫節。
詳細流程圖的問題不僅僅是冗餘。當流程圖與原始碼不一致時，它會變成一個積極有害的誤導工具——維護者依賴過時的流程圖做出修改，反而引入新的臭蟲。
自我文件化的程式#
Brooks 提出一個在當時頗為激進的想法：將文件融入原始碼本身——讓程式自己成為自己的文件。
這個理念的核心動機是：分離維護的文件，必然會與程式碼脫節。 無論多麼嚴格的流程要求，當時間壓力出現時，程式設計師會先改程式碼、「之後再更新文件」——而「之後」永遠不會到來。
自我文件化的十二項技巧#
Brooks 列舉了讓程式自我文件化的具體方法：
- 有意義的命名：變數、函數、模組的名稱應該直接傳達其用途
- 結構化的程式碼：程式的結構本身就表達了邏輯流程
- 註解「為什麼」而非「做什麼」：程式碼已經告訴你它在做什麼，註解應該解釋為什麼要這樣做
- 標頭區塊（header block）：每個模組開頭包含目的、介面、作者、修改歷史
- 標記資料結構：為每個欄位和記錄加上清楚的標籤和說明
- 善用語言特性：利用程式語言提供的命名、格式化、組織功能
自我文件化的理念，在半個世紀後的今天已成為業界共識。現代的 Javadoc、JSDoc、Docstring 等工具，都是 Brooks 這個觀點的延伸實現。「程式碼即文件」不再是激進主張，而是基本的專業實踐。
核心洞見#
Brooks 在本章最深刻的觀察是：文件的問題本質上不是寫作問題，而是維護問題。 任何人都能寫出一份完整的文件。真正的挑戰是讓文件在程式碼不斷演化的過程中，始終保持準確和最新。
自我文件化的解決方案之所以有效，正是因為它從根本上消除了「兩份資訊需要同步維護」的困境。當文件就是程式碼的一部分，更新程式碼的同時就更新了文件。
本章重點#
- 軟體有兩張臉——給機器的和給人的，文件是「另一張臉」，不可忽視
- 使用者文件需要九大要素：目的、環境、領域與範圍、功能、格式、操作說明、選項、執行時間、精確度
- 維護者文件的核心是結構圖，而非詳細的流程圖
- 流程圖被嚴重高估——原始碼本身就是最好的詳細流程圖
- 自我文件化是解決文件與程式碼脫節的根本方案：將文件融入原始碼