「沒時間寫」這個藉口,看似理性,實則危險:
在新增功能 vs. 為既有功能寫文件之間二選一時,新功能總是看起來比較重要。
但軟體專案幾乎永遠在時間壓力下,永遠有更急的事,因此一旦讓寫文件被「降級」→ 你最後就是沒有文件。
反論:投資心態#
對應第 3 章的「投資心態」(investment mindset)。
想要乾淨的軟體結構、想長期有效率工作 → 必須花一些前期時間打造它。
好註解大幅改善維護性,這份投入會很快回本。
寫註解到底要花多少時間?#
讓我們做個小估算:
- 開發過程中,真正在打程式碼的時間佔多少?(不算設計、編譯、測試)
- 估計上限大約 10%
- 假設寫註解花的時間 = 寫程式碼的時間(這是上限,通常更少)
寫好的註解大概只增加總開發時間 10% 左右——好文件帶來的好處很快就會把這個成本抵銷掉。
抽象層次的註解尤其值得#
許多最重要的註解都關於抽象——
- 類別、方法的頂層文件
第 15 章會主張:這些註解應該作為設計過程的一部分來寫。寫註解本身就是一個重要的設計工具,會立即改善整體設計——這類註解寫完當下就回本。