Google C++ 風格指南（六）：程式碼註解藝術

註解核心原則

註解雖痛苦但對可讀性至關重要。**最好的程式碼即文件**——清晰的型別/變數命名勝過解釋模糊命名的註解。註解是寫給下一個讀的人（也可能是未來的你）。

1. 註解風格：// 或 /* */ 統一即可

// 較常見，專案內保持一致。

2. 檔案註解：版權、授權、作者、內容描述

• 頂部依序：版權聲明、授權版本（Apache 2.0/BSD/LGPL/GPL）、作者資訊（重大修改者補充）。
• .h 述類別功能與用法；.cc 述實作細節/演算法。避免單純複製註解導致脫節。

3. 類別註解：功能、用法範例、同步假設

// 迭代 GargantuanTable 內容。用法範例：
// GargantuanTable_Iterator* iter = table->NewIterator();
// for (iter->Seek("foo"); !iter->done(); iter->Next()) 
//     process(iter->key(), iter->value());
// delete iter;
class GargantuanTable_Iterator { ... };

多執行緒存取類別**必須**文件化同步前提。

4. 函式註解：宣告處述「做什麼」，定義處述「怎麼做」

宣告處必含項目

• 輸入/輸出參數說明
• 參考參數生命週期與擁有權
• 記憶體配置與釋放責任
• 參數是否可為 NULL
• 效能隱憂
• 可重入性與同步前提

定義處重點

說明實作技巧、步驟、理由（如為何前半段加鎖後半段不需）。**勿從宣告處複製註解**。

5. 變數註解

• 類資料成員：說明用途、哨兵值（如 -1 代表未知）。
• 全域常數：說明含義與用途。const int kNumTestCases = 6; // 迴歸測試總案例數

6. 實作註解：巧妙、晦澀、關鍵處

• 區塊前註解：解釋複雜演算法邏輯。
• 行尾註解：代碼後兩格空白加註，對齊增強可讀性。
• 參數註解：傳遞 NULL、true/false、魔術數字時必須註解或用常數：
  CalculateSomething(val, 10, false, NULL); // 差
CalculateSomething(val, kDefaultBase, kNotFirstCall, nullptr); // 好

禁忌：自然語言翻譯程式碼（假設讀者 C++ 比你強）。

7. 標點、拼字、語法

完整句子、正確標點、一致風格。易讀的註解勝過爛註解。

8. TODO 註解：標記暫時/不完美方案

// TODO(kl@gmail.com): 這裡應用 * 串接運算子
// TODO(Zeke) 2025-12-31: 改用關聯式存儲
// TODO: 當所有客戶端支援 XML 時移除此代碼

統一 TODO 大寫格式利於搜尋追蹤。