Clang-Format

clang-format 會將原始碼版面配置轉化為儲存庫政策，而不是各作者的個人偏好。它會根據語法 token 串流格式化支援的語言，因此縮排、換行以及許多空格決策都能重現。它不會規範命名、API、擁有權或行為正確性；因此，程式碼審查仍必須檢查這些語意層面的問題。

建立儲存庫政策 #

在儲存庫根目錄提交 .clang-format 檔案。使用 --style=file 時，clang-format 會從每個輸入檔案的位置向其祖先目錄搜尋，並選擇距離最近的 .clang-format 或 _clang-format。因此，巢狀目錄可以刻意覆寫根目錄政策，但意外放置的巢狀檔案也會改變該子樹的結果。

使用明確的 YAML，即使預設樣式提供了預設值，也要包含基礎樣式：

---
BasedOnStyle: LLVM
IndentWidth: 4
ColumnLimit: 100
SortIncludes: CaseSensitive

LLVM、Google、Chromium、Mozilla、WebKit、Microsoft 和 GNU 是內建的基礎樣式。預設樣式名稱不是穩定的儲存庫政策，因為新版 clang-format 可能新增選項或變更預設值。使用 clang-format --style=LLVM --dump-config 產生特定版本的完整起始設定，檢查後提交預期的選項。如果需要逐位元組完全相同的輸出，請在開發環境和 CI 環境中固定格式化工具的版本；明確設定可以降低版本之間的格式差異，但無法消除這些差異。

Language: 區段會針對特定語言擴充預設區段：

---
BasedOnStyle: LLVM
IndentWidth: 4
---
Language: Cpp
PointerAlignment: Left

對於標準輸入或沒有副檔名的檔案，傳入 --assume-filename=example.cc，讓語言偵測和儲存庫探索與目標原始碼相符。

呼叫格式化工具 #

每次呼叫都使用已提交的政策：

# 重寫由建置系統或檔案清單選取的完整檔案。
clang-format --style=file -i src/widget.cc include/widget.h

# 只重寫變更的行。此呼叫中的位移量以位元組為單位。
clang-format --style=file -i --offset=120 --length=400 src/widget.cc

# 在不修改檔案的情況下檢查 CI 檔案集。
clang-format --style=file --dry-run --Werror src/widget.cc include/widget.h

編輯器應在儲存時或執行明確的格式化命令時，使用 --style=file 呼叫 clang-format。CI 應執行相同版本的可執行檔，並且只檢查與專案相關的已追蹤檔案；Shell glob 會遺漏巢狀目錄中的檔案，而且結果可能因 Shell 而異。可供審查的 CI 指令碼可以從 Git 或建置系統取得檔案清單，並在格式化會產生差異時失敗。

--style=file:/absolute/path/to/.clang-format 會選取一個已知檔案，並避免搜尋父目錄。對於產生工具，或不應因子目錄而變化的 monorepo 政策，請使用此選項。

分離版面配置與審查 #

對於特定的格式化工具版本、原始碼、設定和要求的範圍，格式化結果是確定性的。在建立修補程式前執行格式化工具，並將採用格式化策略時的整體重新格式化與功能變更分開。如此一來，審查者可以忽略版面配置雜訊，語意差異也更容易閱讀。

不要將格式化輸出視為編譯器或安全性檢查。clang-format 可以排序 include 並重寫換行位置，但它不會解析 include，也不會驗證編譯結果。只有在產生形式或表格形式無法由政策表達時，才使用文件化的 clang-format off 和 clang-format on 註解來保護特殊版面配置；並在指示旁說明例外原因。