C++ Linter Template

這是一個符合最佳實務、可漸進式導入的 C++ linter 自動化模板。現為 Phase 1：格式嚴格、靜態分析建議不擋流程。

目標

• 對舊 C++ 專案導入 clang-tidy 與 clang-format
• 提供「先格式、後強化」的漸進策略
• 內建 Azure DevOps CI/CD 串接與 PR 差異分析

快速開始（Phase 1）

1) 安裝工具

# Ubuntu/Debian
sudo apt install clang-tidy clang-format cmake build-essential

# macOS
brew install llvm cmake

2) 產出 compile_commands.json（建議）

mkdir -p build && cd build
cmake .. -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cd -

3) 執行 Linter

# 使用腳本（會自動偵測 build/compile_commands.json）
./scripts/run-linter.sh

4) 安裝 Git hooks（建議）

./scripts/setup-hooks.sh

• pre-commit 會自動 clang-format 已 staged 的 C/C++ 檔並要求你重提一次 commit。
• clang-tidy 以建議模式執行（不擋提交）。

5) 建構與執行

mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
make -j$(nproc)
./tests
./main

Phase 1 政策（建議 → 強制的起點）

• 格式：以 .clang-format 為準；CI 以 --dry-run --Werror 強制。
• 靜態分析：.clang-tidy 啟用 clang-analyzer-* 與精選 bugprone-*；僅回報警告，不讓 CI 失敗。
• PR：僅分析變更檔案，加速回饋。

CI 流程（Azure Pipelines）

1. 安裝工具與版本資訊
2. clang-format --dry-run --Werror（不合格式即失敗）
3. 以 CMake 匯出 build/compile_commands.json
4. clang-tidy -p build 掃描（建議模式，不擋流程）
5. Build 專案與執行 ./tests、./main
6. PR Job 僅對變更檔案跑 clang-tidy -p build

自定義規則

• .clang-tidy：Phase 1 強調重大缺陷檢查（例如 analyzer、部分 bugprone）。
• .clang-format：基於 LLVM 風格（IndentWidth=4, ColumnLimit=100）。

文件

• docs/linter-setup.md：本地與 CI 設定流程
• docs/coding-standards.md：編碼與格式規範（Phase 1）

專案結構

cpp-linter-template/ ├── .clang-tidy # linter 配置檔（Phase 1） ├── .clang-format # 格式化配置 ├── azure-pipelines.yml # Azure DevOps CI/CD 配置 ├── CMakeLists.txt # 建構配置（C++98） ├── README.md # 專案說明（本檔） ├── docs/ # 文件目錄 │ ├── linter-setup.md # Linter 設定指南 │ └── coding-standards.md # 編碼標準（Phase 1） ├── src/ # 原始碼 │ ├── main.cpp # 主程式（含測試片段） │ ├── utils.cpp # 工具函數 │ └── utils.h # 標頭檔 ├── tests/ # 測試程式碼 │ └── test_main.cpp # 最小測試（無框架） └── scripts/ # 輔助腳本 ├── run-linter.sh # 本地執行 linter └── setup-hooks.sh # 安裝 pre-commit hooks

後續階段（預覽）

• Phase 2：對關鍵 tidy 規則轉為失敗門檻（資源管理/未定義行為）。
• Phase 3：引入 readability/modernize 並在 PR 變更檔上強制。
• Phase 4：全域強制，警告視為錯誤（需技術債清理完成）。