Qt 官方編碼風格指南完整版：縮進、命名、空白、大括號、控制語句與繼承規範

編輯：關於C語言

Qt 專案組通過挖掘 Qt 源碼、論壇討論、郵件列表及開發者協作，總結出這套編碼風格指南。遵循它能保證代碼風格一致、可讀性強、易於團隊協作與代碼審查。本文完整呈現核心規範，附帶正反例對比。

一、縮進與空白

縮進：4 個空格，**嚴禁 Tab 鍵**。
空行分組：邏輯相關語句間用單個空行分隔，不空多行。
關鍵字與大括號：`if (condition) {`、`while (cond) {`、`for (...; ...; ...) {` — 關鍵字與 `{` 之間保留一空格。
指標/引用宣告：類型與 `*`/`&` 間有空格，`*`/`&` 與變量名無空格。
```
char *ptr;
const QString &ref;
const char * const constPtr = "text";
```
二元運算符：前後各一空格：`a + b`、`x == y`。
類型轉換：轉換運算符後無空格：`reinterpret_cast<char*>(ptr)`。

二、變量宣告與命名

每行一個變量，便於註釋與差異比對。
避免縮寫：`height`/`width` 而非 `h`/`w`；`nameOfThis` 而非 `noth`。
單字符變量：僅用於迴圈計數器 (`i`, `j`, `k`) 或極短作用域臨時變量。
就近宣告：在首次使用前才宣告，縮小作用域。
命名規則：
- 變量/函數：駝峰式，首字母小寫 — `itemDelimiter`、`setText()`。
- 常量/枚舉值：全大寫下劃線 — `MAX_BUFFER_SIZE`。
- 類/結構體：駝峰式，首字母大寫 — `QNetworkRequest`。
- 公有類常以 `Q` 開頭 (`QRgb`)，公有函數常以 `q` 開頭 (`qRgb`)。

正反例

錯誤	正確
`int a, b; char c, d;`	`int height; int width; char nameOfThis; char nameOfThat;`
`short Cntr; char ITEM_DELIM = '\t';`	`short counter; char itemDelimiter = '\t';`

三、大括號風格：K&R 變體

原則：左大括號與語句同行，**除函數定義與類定義外**。

控制語句：同行


// 正確
if (condition) {
    doSomething();
}

// 錯誤
if (condition)
{
    doSomething();
}

函數與類定義：左大括號獨佔一行


void foo(int g)
{
    qDebug("foo: %i", g);
}

class Moo
{
};

單行語句體：可省略大括號


// 正確
if (address.isEmpty())
    return false;

for (int i = 0; i < 10; ++i)
    qDebug("%i", i);

強制加大括號的例外

父語句跨多行：

if (address.isEmpty() || !isValid()
    || !codec) {
    return false;
}

`if-else` 任一分支跨多行：

// 錯誤
if (address.isEmpty())
    return false;
else {
    qDebug(...);
    ++it;
}

// 正確
if (address.isEmpty()) {
    return false;
} else {
    qDebug(...);
    ++it;
}

巢狀 `if` 消除 `else` 歧義：

// 錯誤：else 屬於哪個 if？
if (a)
    if (b)
        ...;
    else
        ...;

// 正確：外層加大括號
if (a) {
    if (b)
        ...;
    else
        ...;
}

空語句體：`while (condition) {}` 而非 `while (condition);`。

四、圓括號：消除優先級歧義

複雜邏輯表達式**必須加圓括號**分組：`if ((a && b) || c)` 而非 `if (a && b || c)`。
位運算混合算術：`(a + b) & c` 而非 `a + b & c`。

五、Switch 語句規範

`case` 標籤與 `switch` 對齊 (同縮進層級)。
每個 `case` **必須** 以 `break`/`return` 結束，或註釋 `// fall through` 說明故意貫穿。
`default` 分支**不可省略**，即使為空也寫 `break`。


switch (myEnum) {
case Value1:
    doSomething();
    break;
case Value2:
    doSomethingElse();
    // fall through
default:
    defaultHandling();
    break;
}

六、換行策略：逗號留尾，運算符領頭

行長限制：**< 100 字符**。

長表達式換行時：逗號留在行尾，運算符移到下行行首。


// 正確
if (longExpression
    + otherLongExpression
    + otherOtherLongExpression) {
}

// 錯誤：行尾運算符易被窄編輯器截斷
if (longExpression +
    otherLongExpression +
    otherOtherLongExpression) {
}

七、繼承與 `virtual` 關鍵字

子類重寫虛函數時，**頭文件聲明中不寫 `virtual`** 關鍵字。
實現文件中同樣不寫。
C++11 可用 `override` 標識符 (Qt 專案常需支援舊編譯器，視專案 C++ 標準而定)。

八、類型轉換：拒絕 C 風格，擁抱 C++ 風格


// 錯誤
char *mem = (char *)malloc(size);

// 正確
char *mem = reinterpret_cast<char*>(malloc(size));
// 或更好：使用 new / 智能指針 / QByteArray / std::vector

九、通用例外條款

如果規則讓代碼變醜，你可以打破它。

風格指南服務於可讀性與維護性，而非教條。在極少數情況下 (如高度優化的底層代碼、與第三方風格對接)，靈活變通優於死守規則。

十、工具鏈支援

clang-format：配置 `.clang-format` 基於 `Qt` 風格預設 (`BasedOnStyle: Qt`)，自動格式化。
Qt Creator：內建代碼風格設置 (Tools → Options → C++ → Code Style)，可導入/導出 `.xml` 共享團隊配置。
C++ Linter：`clang-tidy` 檢查命名、現代化、效能等問題。

將此風格指南內化為肌肉記憶，並配合自動化工具強制執行，是打造高質量 Qt/C++ 代碼庫的基石。