副標：Use Comments As Part Of The Design Process（用註解作為設計過程的一部分）
多數開發者把寫註解延到最後（編碼與單元測試完成之後）——這幾乎是保證寫出爛文件的方式。
寫註解最好的時機 = 一開始，在你寫程式碼的同時。
「先寫註解」會：
- 把文件納入設計過程
- 產出更好的文件
- 產出更好的設計
- 讓寫文件變成樂趣
延後寫註解的代價#
開發者問「為什麼還沒寫文件？」常見回答：
「程式碼還在變，先寫等下要重寫，等程式碼穩定再說。」
但作者懷疑還有另一個原因：他們把寫文件當苦工，能拖就拖。
後果一：文件最後根本不會寫#
- 開始拖一拖很容易再拖久一點
- 等到「真的穩定」時，未寫文件的程式碼累積到嚇人
- 「停幾天補完」永遠不是好時機；理性化成「修 bug 或寫新功能對專案更重要」
- 結果：未寫文件的程式碼越積越多
後果二：就算回頭寫，品質也很糟#
別騙自己——你多半不會真的回頭寫。
即使你回頭：
- 心理上你已「結案」這段程式碼
- 急著做下一個專案
- 知道該寫，但不有趣 → 趕快了事
- 設計的記憶開始模糊
- 寫註解時得邊看程式碼邊寫 → 註解就成了重複程式碼
- 即便試著補當初的設計理由，也已經想不起來
結果：缺漏的剛好是文件最該描述的那些事。
先寫註解的具體流程#
作者的流程：
- 新類別 → 先寫類別介面註解
- 寫最重要的 public 方法的介面註解與簽章（方法主體留空）
- 在這些註解之間反覆迭代，直到基本結構大致對勁
- 寫最重要的 instance 變數的宣告與註解
- 填入方法主體，按需要加上實作註解
- 寫主體時往往會發現需要更多方法 / 變數 → 新方法先寫介面註解再寫主體；新變數邊宣告邊寫註解
程式碼完成時，註解就完成了。永遠不會有「待寫文件」的積欠。
益處 1：更好的註解#
- 寫註解時設計議題還新鮮 → 更容易記錄
- 在寫方法主體前先寫介面註解 → 能聚焦於抽象與介面，不被實作分心
- 編碼與測試過程會發現註解的問題 → 註解隨開發越改越好
益處 2：把註解當設計工具#
這是「先寫註解」最重要的好處：改善系統設計。
- 註解是唯一能完整捕捉抽象的工具
- 好的抽象 = 好的系統設計的基礎
- 在寫實作前就描述抽象 → 能在寫程式碼前審視與調整
- 寫好註解必須先找出實體的本質：什麼是最重要的？早期想清楚 → 不再只是亂打程式碼
註解作為複雜性的「煤礦坑金絲雀」#
若一個方法或變數需要長段註解 → 紅旗：你沒有好抽象。
- 第 4 章說過：類別應深，介面簡單而功能強
- 判斷介面複雜度最好的方法 = 看描述它的註解
- 介面註解短而完整 → 介面簡單
- 必須長而複雜才描述得完 → 介面複雜
- 把介面註解與實作對比 → 看出方法的「深度」
- 介面註解必須描述實作所有主要特性 → 方法太淺
同理適用於變數。
紅旗：難以描述（Hard to Describe）#
描述方法或變數的註解應簡單而完整。
若你寫不出這樣的註解，那是設計有問題的訊號。
註解只在它完整且清楚時才是複雜性的好指標。寫得殘缺或晦澀的註解，無法用來衡量深度。
益處 3：早寫註解 = 寫起來有趣#
對作者而言，新類別早期的設計階段是程式設計最享受的部分：
- 在 flesh out 抽象與結構
- 多數註解就是這時寫的
- 註解是他記錄與測試設計品質的工具
- 目標：用最少的字完整、清楚地表達設計
- 註解越簡單 → 對設計越自豪 → 找到簡潔的註解是一種樂趣
若你採取戰略型程式設計（主要目標是好設計而非「能跑就好」），那麼寫註解就會有趣——它就是你辨識最佳設計的方法。
早寫註解很貴嗎？#
讓我們算一筆數：
- 程式碼 + 註解總打字時間（包含修改）大概不超過總開發時間的 10%
- 即使一半行數是註解，寫註解最多也只佔總開發時間 5%
- 把註解延後省下來的就只是這一小部分的一部分而已
而且：
- 先寫註解 → 抽象在寫程式碼前就更穩定 → 省下程式碼層次的修改成本
- 反之先寫程式 → 抽象隨著編碼演化 → 程式碼修改更多
把所有因素算進來，先寫註解整體上甚至可能更快。
結語#
沒試過「先寫註解」？試試看。
堅持夠久讓自己習慣，再回頭評估：
- 註解品質
- 設計品質
- 寫程式的整體愉悅度
試一陣子後，看看你的經驗是否與作者相符。