程式碼撰寫風格指南：可讀、可維護、專業的視覺規範

前言

「代碼是給人看的，順便能在機器上跑。」好的撰寫風格不僅關乎美觀，更直接影響團隊協作效率、代碼審查品質、長期維護成本。許多軟體公司將風格規範納入強制規範（縮排、命名、空行、註解密度等）。本文從視覺層面剖析優良風格的核心要素。

一、縮排：結構的骨架

Tab vs Space

• Tab：鍵入快、檔案小、寬度可配置（建議 4 格）。缺點：不同編輯器顯示不一，混合編輯易亂。
• Space：顯示完全一致、版本控制 diff 乾淨。缺點：鍵入慢、檔案稍大。
• 建議：團隊統一 **Tab = 4 格**，並開啟編輯器「Tab 轉 Space」或「Space 轉 Tab」功能，提交前統一格式化。

何處必須縮排

// 1. 控制結構層級
void Alert(int i) {
    while (i > 0) {          // 層級 1
        Beep(1000, 1000);    // 層級 2
        i--;                 // 層級 2
    }
}

// 2. 變數集中宣告對齊
int     i;
DWORD   dwData;
LPTSTR  lpszName;

// 3. 多參數函數呼叫換行對齊
CreateWindowEx(
    0,
    "MyClass",
    "My Window",
    WS_OVERLAPPEDWINDOW | WS_HSCROLL | WS_VSCROLL,
    CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT,
    (HWND)NULL, (HMENU)NULL, hInstance, NULL
);

二、空格：呼吸的節奏

• 參數分隔：TextOut(hDC, 10, 10, "Testing...", 10);
• 運算子兩側：i = 10 * (123 + 100 / 5);
• 邏輯表達式：if ((a > b) && (c < d) && (e == f))
• 關鍵字後：if (cond) { while (cond) { for (;;) {
• **禁忌**：函數名與左括號間加空格（Func (x)），括號內側加空格（( x )）。

三、空行：模組的分隔符

原則：**相關緊湊、不相關分隔**。具體：

1. 獨立邏輯塊前後各一空行（如初始化、計算、輸出）。
2. 功能相似代碼群組前後空行（如連續的 Get/Set 方法）。
3. 形式相似代碼群組（如連續的案例處理）。
4. 函數/方法之間**至少一空行**，公開介面與內部實作間**兩空行**。
5. 檔案結尾保留一空行（POSIX 標準）。

四、命名：代碼的語義標識

核心原則

1. 前後一致：GetXPos() / GetYPos()，不可混用 GetYPosition()。
2. 望文生義：cursorX 優於 cx；maxRetryCount 優於 mrc。
3. 遵循平台慣例：MFC 用 m_var、Get/Set、OnEvent；Qt 用 m_var、camelCase；Linux 核心用 snake_case。
4. 拒絕拼音：userName 而非 yongHuMing；不懂英文查字典，養成國際化習慣。
5. 常數全大寫+底線：MAX_BUFFER_SIZE；巨集同樣。
6. 類別/類型 PascalCase：CSerialPort；變數/函數 camelCase：openPort()。

五、註解：文檔的就地化

• 檔案頭：版權、作者、日期、功能摘要、修改記錄。
• 函數頭：用途、參數、回傳、副作用、異常、演算法說明。
• 關鍵演算法/業務邏輯前**必須**有註解。
• 註解密度：非標頭註解行數佔總行數 1/5 ~ 1/3。
• 註解與代碼同步更新，**過期註解比無註解更害人**。
• 明顯代碼（如 i++;）免註解。

六、結構化原則：邏輯的守門員

• 單一出口：函數僅一 return（守衛子句除外）。
• 禁止 goto、else goto、else return。
• 多路分支用 switch/查表法，避免超過 5 層巢狀 if/else。
• 迴圈單一入口、單一出口，避免多重 break/continue。
• 優先用邏輯表達式替代條件分支：return a > 0 && b < 10;

七、總結

風格規範不是束縛，而是**自由的前提**——統一風格讓團隊成員能專注於業務邏輯而非格式糾葛。建議團隊採用成熟指南（Google C++ Style Guide、LLVM Coding Standards、Microsoft All-In-One Code Framework）並配合 clang-format/uncrustify 自動化強制執行。從今天開始，寫出讓同事（包含半年後的自己）讀起來舒服的代碼。