C++ 註解完整指南：單行、多行、文件化註解與最佳實務

註解 是原始碼中的說明性文字，編譯器完全忽略，僅供開發者閱讀維護。良好的註解是專案可維護性的基石。

兩種基本註解語法

單行註解 //

從 // 至行尾。可獨佔一行或置於程式碼後：

// 這是單行註解
int x = 10; // 初始化 x

多行註解 /* ... */

跨越多行，不可巢狀 (標準 C++)：

/* 這是多行註解
   可以跨越多行
   說明複雜演算法邏輯 */

註解巢狀規則

• /* ... */ 內部的 // 無特殊意義，視為普通文字。
• // 內部的 /* */ 亦無特殊意義。
• 因此可用單行註解暫時停用包含多行註解的程式碼區塊：

// /*
// int x = 10;
// /* 內部多行註解 */
// int y = 20;
// */

文件化註解

配合工具 (Doxygen、Javadoc 風格) 自動產生 API 文件。常用標籤：

Doxygen 風格範例

/**
 * @brief 計算兩整數最大公因數
 * @param a 第一個整數
 * @param b 第二個整數
 * @return 最大公因數
 * @throw std::invalid_argument 若輸入為負數
 */
int gcd(int a, int b) {
    if (a < 0 || b < 0) throw std::invalid_argument("negative");
    while (b) { int r = a % b; a = b; b = r; }
    return a;
}

註解最佳實務

編譯器擴充：屬性語法 (C++11)

[[deprecated("use newApi()")]]、[[nodiscard]]、[[fallthrough]] 等標準屬性可取代部分註解功能，編譯器直接檢查。

總結

• 掌握 // 單行與 /* */ 多行兩大語法，理解巢狀規則。
• 公共介面採用 Doxygen 風格文件化註解，自動產生專業 API 文件。
• 遵循「解釋為什麼、保持同步、避免雜訊」核心原則。
• 善用 TODO/FIXME、標準屬性輔助維護流程。