程式碼風格指南：寫出可維護、專業的 C++ 代碼

資深工程師與新手最大的差異，往往不在於演算法多麼高深，而在於「風格」。良好的程式碼風格能降低認知負荷、減少缺陷、加速團隊協作。本文整理自 Scott Cross 經典文章，結合現代 C++ 實務，提供 23 條核心風格建議與文檔規範。

為什麼風格至關重要？

• 可讀性：程式碼給人讀的次數遠超給機器執行的次數。
• 可維護性：統一風格讓接手者快速定位邏輯，降低「不敢動」的恐懼。
• 專業度：整潔的代碼反映工程師的嚴謹態度，建立團隊信任。

23 條核心風格建議

1. 有意義的命名：totalGrades 優於 y，maxGrades 優於 x。
2. 迴圈計數器慣例：i, j, k, l, m 保留給迴圈，源自 Fortran 習慣。
3. 右大括號註釋：長區塊結尾加 // end if、// end for，快速對應開頭。
4. 左大括號另起一行：if (cond)\n{\n 方便視覺對齊與摺疊。
5. 善用複合指派：total += grade、i++ 產生更優組合語言（inc vs mov/inc/mov）。
6. 精準註釋：複雜邏輯必註，直觀流程免註；註釋與代碼同步維護。
7. 駝峰式大小寫區分型別：簡單型別 int count，複雜型別 CustomerList，單字首字母大寫。
8. 避免底線：編譯器保留字常含底線，易衝突。
9. 適度模組化：邏輯獨立成函式，促進複用與測試，切忌過度封裝。
10. 選對迴圈：至少一次 do-while，條件未知 while，次數固定 for。
11. 多重分支用 switch：>2 分支優先 switch，必加 default，效率優於 if-else 鏈。
12. 邏輯區塊留白行：變數宣告、迴圈、條件之間空一行，視覺分段。
13. 變數就近宣告：區域變數在最小作用域宣告，減少生命週期與副作用。
14. 必須初始化：所有變數宣告即賦值，消除未定義行為。
15. 非 void 函式全路徑 return：編譯器警告 function should return a value 視為錯誤處理。
16. 隱含轉型顯式轉換：float f = static_cast<float>(i) 消除警告，文檔化意圖。
17. 釋放後歸零：delete p; p = nullptr; 防野指標。
18. 勿重造輪子：優先用標準庫/成熟庫，專注核心業務邏輯。
19. 拼字正確：拼字錯誤導致搜尋失效、誤導維護者。
20. 禁用大小寫唯一區別：count vs Count 極易混淆。
21. 即時寫註釋：寫代碼時同步完成，事後補註釋幾乎不會發生。
22. 除錯註釋碼最後刪除：// 掉的代碼上線前必清。
23. 一致性至上：團隊統一風格，個人偏好服從集體規範。

標準化檔案頭文檔模板

/*
Written by: Scott Cross
Date originally Completed: 1999-09-18
Purpose: Main routine for NY Billing...
Usage:
    bool LoadAcctInfo(
        String policyNo,        // 目標保單號
        bool printInvoice,      // 是否列印發票
        bool nightRunning,      // 夜間批次模式
        bool payableRunning,    // 會計報表模式
        String masterPrintDate  // 基準日期
    );
No preliminary logic needed. Returns true in most cases.
Struct InvoiceInfoStruct { ... }; // 詳細欄位說明見原文
Update History:
    1999-09-18 - Scott - Completed
    2000-02-01 - Scott - Fixed totalPaid error on cancelled file
*/

UI 輸出風格建議

1. 統一字型與大小，支援系統大字型與 640×480 16 色最低解析度。
2. 多色系測試（高對比、深色模式）。
3. 保持 3D 凸起/凹入一致性，賦予介面層次感。
4. 長時間操作呼叫 Application->ProcessMessages() 保持回應。
5. 工具提示與狀態列提示全覆蓋。
6. 精靈式介面引導複雜多步驟流程。
7. 避免花俏特效，除非專案需求。

結語

養成良好風格約需六週，受益卻是職涯一生。從今天開始，把每一行代碼都當作給未來的自己與同事看的文獻來書寫。

原著：Scott Cross | 翻譯：cker | 來源：國外技術社群整理