C/C++ 編碼規範總結：從命名風格到性能優化的工程實踐指南

編碼規範的核心目標統一：在高質量完成需求的同時，保證代碼的可讀性、可維護性、可移植性。本文整理自項目組經驗，參考 GNU、C++ Core Guidelines、Google Style Guide 等主流規範，不適用於所有場景，請按需採納。

一、文件組織與排版

頭文件包含順序

1. 系統頭文件（穩定路徑用子路徑：#include <xxx/yyy.h>）
2. 用戶頭文件（不穩定路徑在編譯選項指定，用 #include "xxx.h"）
3. 僅引用必要頭文件，減少編譯依賴

文件命名

• 頭文件：*.h，內聯文件：*.inl，實現文件：*.cpp
• 大小寫混合（如 DiyMainView.cpp）或全小寫，避免無意義縮寫（XImage.cpp ❌）

頭文件結構

#ifndef MODULE_FILE_H
#define MODULE_FILE_H

// 1. 包含塊
// 2. 宏定義塊
// 3. 全局常量/變量
// 4. 類型定義
// 5. 類定義
// 6. 內聯函數

#endif // MODULE_FILE_H  // 行尾註釋

空行規範

• 文件頭、控制塊、#include、宏、類、全局常量/變量、函數之間：兩個空行
• 函數體內邏輯相關語句不空行，其餘加空行分隔

二、註釋規範

• 文件頭：作者、文件名、說明、日期
• 關鍵函數：用途、參數說明（所有權轉移）、返回值、異常情況
• 位置：註釋寫在代碼之前，非行尾
• 特殊標記：// TODO、// NOTE、// DEBUG、// end for/while
• 預處理：每個 #else/#endif 加行尾註釋

三、命名規範

通用原則

• 英文單詞組合，可拼讀、望文知義，拒絕拼音
• 長度最小化 & 信息量最大化平衡
• 避免僅大小寫區分（i/I）、不同作用域重名、數字編號（Value1/Value2）
• 互斥語義用反義詞：Min/Max、Get/Set、Begin/End

前綴約定

風格兼容

移植/開源代碼保持原風格，不強制統一。

四、代碼風格細節

縮進與對齊

• 行首縮進只用 Tab，內容對齊用空格（跨編輯器顯示一致）
• 行尾禁留空格
• :: -> . 前後不加空格；, ; 前不加空格

大括號風格

• 類/結構/枚舉/函數：{ 另起一行
• if/for/while/do/try/catch：{ 同行或另起，執行語句必須加 { }（防修改出錯）
• else：} else { 同行

Switch 語句

• case 與 switch 對齊
• 有變量的 case 用 { } 包裹
• 必須有 default 分支
• 無 break 必加註釋

類設計

• 繼承列表每行一個基類，Tab 對齊
• 虛函數不帶默認參數，功能單一
• 可繼承類析構函數必為 virtual
• 不可複製類：private 拷貝構造/賦值運算符

五、類型與表達式

• * & 緊貼類型：int* p、int& ref
• 避免浮點數直接比較 ==/!=
• 用 enum 替代常量組，拒絕魔鬼數字
• 優先用引用替代指針
• 定義變量即初始化
• 避免 union、無名類型、強制轉換

六、函數設計

• 參數只讀用 const T&，需修改用 T&，簡單類型傳值
• const 成員函數盡量多用
• 內聯函數僅用於簡單邏輯，虛函數不內聯
• 返回引用/指針必須標註生命週期

七、錯誤處理與資源管理

• new/delete、new[]/delete[] 成對使用
• 申請後必檢查失敗，釋放後置 nullptr 防野指針
• 誰申請誰釋放（函數級 > 類級 > 模塊級）
• 衛語句風格：先處理錯誤返回，再處理正常邏輯
• do-while(0) 宏包裹多語句為單語句
• 零編譯警告

八、性能優化原則

• 前向聲明替代 #include
• ++i 優於 i++（避免臨時對象）
• 循環不變量外提
• 避免循環內定義對象、避免昂貴拷貝、避免大臨時對象
• 80/20 原則：優化熱點 20% 代碼

九、兼容性與可移植性

• 遵循 ANSI C / ISO C++ 標準
• 不假設類型大小、求值順序、初始化順序
• 雙字節字符兼容、溢出檢查
• #include 文件名視為大小寫敏感
• 慎用全局/靜態變量（多線程/動態庫環境下風險）
• 不重複造輪子（優先用 STL/標準庫）

總結

規範非束縛，而是團隊協作的「契約」。好的規範讓代碼可讀、可理、可改、可測。建議團隊根據項目特點裁剪形成《項目編碼規範》，配合 Code Review 與靜態分析工具（Clang-Tidy、Cppcheck）落地執行。