註解的核心目的#

註解的本質：捕捉那些存在於設計者腦中、卻無法以程式碼表達的資訊。

涵蓋範圍從低層到高層：

• 低層：某段棘手程式碼背後的硬體怪癖
• 高層：某個類別存在的理由（rationale）

對未來開發者的價值#

• 沒有註解 → 後來的開發者只能憑猜或重新推導設計者當初的知識
• 多花時間，且若誤解原意 → 引入 bug

即使「未來的開發者」就是你自己——幾週後再回來看自己的程式碼，許多細節已經忘光。註解仍價值滿滿。

對應到第 2 章的三種複雜性徵兆#

沒有充足文件時，開發者得閱讀大量程式碼才能拼出當初設計者的構思。

文件可以澄清依賴，填補模糊——直接針對複雜性的兩個根本成因。

後續章節導引#

下一章開始示範怎麼寫好註解，並說明如何把寫文件融入設計流程，讓它反過來改善設計品質。