寫註解的第一步：決定慣例。包括「要為什麼東西寫註解」、「使用什麼格式」。

採用工具的慣例#

如果你的語言有文件編譯工具，依工具的慣例：

• Java → Javadoc
• C++ → Doxygen
• Go → godoc

這些慣例都不完美，但工具帶來的好處足以彌補。

沒有現成慣例的環境？借用相近語言或專案的慣例——讓其他開發者更容易理解與遵守。

慣例的兩個用途#

1. 一致性：讓註解更易讀、易懂
2. 督促你真的去寫：沒有清楚的「要寫什麼、怎麼寫」 → 結果就是什麼都不寫

註解的四個常見類別#

1. 介面註解（Interface comment）#

模組宣告（class、struct、function、method）正前方的註解區塊：

• 描述模組的介面
• 類別：整體抽象
• 方法 / 函式：行為、參數、回傳值、副作用、可能拋出的例外，以及呼叫前必須滿足的前置條件

2. 資料結構成員註解（Data structure member comment）#

資料結構欄位旁的註解（class 的 instance / static 變數）。

3. 實作註解（Implementation comment）#

方法 / 函式內部的註解，描述程式碼如何運作。

4. 跨模組註解（Cross-module comment）#

描述跨越模組邊界的依賴關係。

哪些一定要寫#

必寫：

• 每個類別都要有介面註解
• 每個類別變數都要有註解
• 每個方法都要有介面註解

偶爾宣告本身明顯到沒什麼可加（getter / setter 有時屬此類），但這種情況罕見。

**與其耗神判斷「需不需要」，不如全部寫——**這通常更省力、更可靠。

寫得頻率較低的兩類#

• 實作註解：通常不必（見 13.6 節）
• 跨模組註解：很少寫，且難寫；但需要時極為重要（見 13.7 節）