C++ 程式風格指南：命名、排版、註解與檔案結構規範

本文翻譯自 1996 年經典《Elements of Programming Style — C++ Style Guide》，雖年代久遠，但核心原則 (一致性、可讀性、可維護性) 至今仍是現代 C++ 編碼規範基石。內容涵蓋檔案組織、命名慣例、空白與縮排、換行規則、註解風格，附完整頭檔與實作檔範本。

一、檔案結構

• 標頭檔：.h 副檔名，含類別/結構/聯合宣告、列舉、#define, typedef
• 實作檔：.cc (UNIX) / .cpp (Windows)，含函數/方法實作
• 檔案標頭：模組名、專案、作者、日期、版本、說明、專案關聯資訊

二、符號名稱對照表

char 讀音建議「charcoal」首音節，或 "care"/"car"。

三、命名慣例

具體應用

• enumeration_item_name (列舉)
• variableName (變數)
• TypeName, ClassName, MethodName() (型別/類別/方法)
• UnixFileName.cc (Unix 檔名)
• dosfn.cpp (DOS/Windows 檔名，全小寫)
• POUND_DEFINES (巨集)

四、空白與縮排規則

• 縮排：左大括號後每行縮進 4 空格，至對應右大括號
• 無大括號控制結構：if/while/for 後無大括號時，下一行縮進 2 空格
• 標籤/存取指定符：public:, case 等冒號結尾行，反向縮進 2 空格
• 保留字：if, else, class, struct 前後各 1 空格
• 運算子：二元運算子/比較運算子前後各 1 空格 (除 ! 外)
• 指標/參考宣告：int *ptr;, int &ref; 符號前後各 1 空格
• 指標/參考使用：表達式中符號前 1 空格 (p = * ptr;)
• 左括號後：if ( condition ) 左括號後 1 空格

五、換行規則

• 類別/函數定義：class, struct, union, enum, method, function 的左大括號後換行
• 控制結構：if, else, do, for, while, switch 的左大括號後不換行，僅 1 空格
• 右大括號後：方法/函數/控制結構的右大括號後換行
• 類別/結構/聯合：右大括號後換行並空一行

六、註解規範

• 註解從目前縮排開始：// 註解內容 (雙斜線後 1 空格)
• 禁止巢狀註解
• 註解置於被描述對象之前
• 使用完整句子，宣告處可用祈使句 (// Initialize member data)

七、標頭檔範本 (ClassName.h)

// MODULE NAME: ClassName.h
// PROJECT: CS1344-1,2 Course Notes
// AUTHOR: Neill Kipp
// DATE: January 1, 1996
// DESCRIPTION: C++ class declaration style examples

#ifndef ClassName_h
#define ClassName_h

#include "super.h"
#include "other.h"

enum OverflowState {
    no_overflow,
    overflow_occurred, // 尾端逗號便於增刪項目
};

class ClassName {
    int memberData; // 說明置於上方或行尾
public:
    ClassName();                 // 建構子初始化成員
    ~ClassName();                // 解構子保證清理
    OverflowState IncrementMemberVariable(int howMuch); // 回傳溢位狀態
    void ShowOverflow(OverflowState overflow);          // 顯示溢位訊息
};

#endif

八、實作檔範本 (ClassName.cc)

// MODULE NAME: ClassName.cc
// PROJECT: CS1344-1,2 Course Notes
// AUTHOR: Neill Kipp
// DATE: January 1, 1996
// DESCRIPTION: C++ class implementation style examples

#include "ClassName.h"

ClassName::ClassName() {
    memberData = 0; // 先寫註解，再寫程式碼
}

OverflowState
ClassName::IncrementMemberVariable(int howMuch) {
    if (TOO_BIG - memberVariable > howMuch) {
        return overflow_occurred;
    } else {
        return no_overflow;
    }
}

void
ClassName::ShowOverflow(OverflowState overflow) {
    switch (overflow) {
    case no_overflow:
        cout << "No overflow occurred.\n";
        break;
    case overflow_occurred:
        cout << "Warning: overflow occurred.\n";
        break;
    }
}

九、其他程式碼片段範例

// for 迴圈空白與縮排
for (whichItem = 0; whichItem < BIG_NUMBER; whichItem++) {
    DoSomething(whichItem);
}

// while 迴圈：! 後無空格
while (!SemaphoreOK()) {
    DoWaitForSemaphore(LONG_TIME);
}

十、現代視角補充

• 現代 C++ 建議：clang-format 自動化格式化、.editorconfig 跨 IDE 一致性
• 命名：Google/LLVM 風格採用 snake_case (變數/函數)、PascalCase (類別/型別)、kConstantName (常數)
• 註解：Doxygen//// 格式支援文件自動生成
• 檔案：標頭檔 .hpp、模組介面 .ixx (C++20 Modules)
• 核心精神不變：一致性 > 個人偏好，團隊共識高於個人習慣

這份 1996 年的指南或許在細節上顯得古老，但它確立的「可讀性優先、機械化排版、註解即文件」工程文化，正是現代軟體工程規範的源頭之一。