C++ 程式風格指南：命名、排版、註釋與自成檔代碼規範

文件組織

• 頭文件：.h (C++ 建議 .hpp) — 類/結構/聯合聲明、枚舉、#define/constexpr、typedef/using。
• 實現文件：.cpp (Windows) / .cc (Unix) — 函數/方法定義。
• 文件頁眉：版權、作者、日期、模組說明、版本歷史、專案歸屬。

符號標準讀音 (團隊溝通統一)

命名約定

排版與空白規則

• 縮進：4 空格 (禁用 Tab)；左大括號換行或行尾 (團隊統一)，右大括號獨佔行並與對應關鍵字對齊。
• 控制結構：if/while/for 後無大括號時，下一行縮進 2 空格 (不推薦省略大括號)。
• 標籤/訪問聲明：public:、case 1: 反向縮進 2 空格 (相對類/函數體)。
• 運算符前後：二元運算符左右各 1 空格 (如 a + b)；一元運算符緊貼操作數 (!flag, ++i)。
• 指針/引用聲明：T* p / T& r (星號/號貼近類型)；表達式中 *p 星號前 1 空格。
• 括號內：( 後、) 前不加空格；if (cond)。
• 行長：建議 ≤ 100/120 字符，超過換行縮進 8 空格 (兩級)。

自成檔代碼原則

1. **零魔數**：除 0/1 外，所有字面值常量提取為 constexpr/enum class，賦予語義名稱。
2. **完整拼寫**：變量/函數名不縮寫 (如 calculateTotalPrice 而非 calcTotPrc)，除非領域通用縮寫 (HTTP, URL, ID, XML)。
3. **契約式註釋**：函數頭標註 // Pre: ... Post: ... 或 Doxygen @pre @post @param @return。
4. **斷言文檼化**：assert(ptr != nullptr); 即是最佳註釋。
5. **TODO/FIXME 標準化**：// TODO(author): description，IDE 可追蹤。

現代 C++ 風格補充 (C++11/14/17/20)

工具落地

• **格式化**：clang-format (配置 .clang-format 統一團隊風格)，CI 強制檢查。
• **靜態分析**：clang-tidy, Cppcheck, PVS-Studio，編譯期捕獲風格/邏輯問題。
• **代碼審查清單**：包含命名、排版、魔數、智能指針、const 正確性、異常安全、測試覆蓋。

總結

風格指南非束縛，而是**降低認知負荷、消除歧義、啟用工具鏈自動化**的契約。團隊共識 > 個人偏好；一致性 > 完美性；工具強制 > 人工檢查。