寫註解的理由：程式語言的敘述無法捕捉所有當初寫程式時存在於開發者腦中的重要資訊。
註解記錄這些資訊，讓後來的人能輕鬆理解與修改。
指導原則：註解應描述「無法從程式碼看出」的事。
哪些事情程式碼看不出來#
- 低層細節：例如一對索引描述某範圍時，端點是否包含？
- 為什麼：為什麼需要這段程式碼？為什麼這樣實作？
- 規則 / 不變式：例如「永遠先呼叫 a 再呼叫 b」——你也許能從整段程式碼推導出來，但這痛苦又易錯
- 抽象：抽象的核心就是把複雜性藏起來；若使用者得從程式碼推抽象，就失去抽象的意義
註解的核心承諾#
開發者應該光看模組對外的宣告（加上註解），就能理解模組提供的抽象——而不必讀任何程式碼。
要做到這點的唯一途徑：用註解補強宣告。
本章脈絡#
- 選定慣例
- 別重複程式碼
- 用低層註解提供精確度
- 用高層註解強化直覺
- 介面文件
- 實作註解：寫 what 與 why，不寫 how
- 跨模組設計決策
結語#
「顯而易見」是從第一次讀你程式碼的人的角度看的，不是從你的角度。
寫註解時，把自己放進讀者的腦袋：他需要知道什麼？
如果你的程式碼正在被審查，審查者說「這個不顯而易見」，不要爭論。
讀者覺得不顯而易見就是不顯而易見。試著理解他困惑的點，用更好的註解或更好的程式碼釐清。