C / C++ / 系统课时
用 clang-format 统一代码格式
用 clang-format 统一代码格式
多人协作时,手工约定缩进和括号风格很容易漂移。clang-format 可以把格式规则写进仓库,并用同一条命令在本地和 CI 中执行。本节会完成规则文件、格式化操作和可自动判定的校验流程。
学习目标
- 能创建项目级
.clang-format并理解常用规则 - 能对单个 C 文件执行预览、原地格式化和校验
- 能把格式检查接入提交或 CI 流程,避免风格反复变化
把规则放进仓库
clang-format 会从目标文件所在目录向父目录查找 .clang-format。因此通常把它放在项目根目录,并与源码一起提交。团队成员和 CI 使用同一份文件,格式规则才真正可复现。
下面是一份偏保守的项目级配置:
BasedOnStyle: LLVM
IndentWidth: 4
TabWidth: 4
UseTab: Never
ColumnLimit: 100
BreakBeforeBraces: Attach这份配置以 LLVM 风格为基础,再覆盖缩进、制表符、行宽和大括号策略。配置文件本身不会修改代码,只有运行 clang-format 时才会生效;后续可用 --dry-run --Werror 验证源码是否已经符合规则。
先预览再修改
假设 src/main.c 当前内容如下。这里故意把多条语句挤在一起,用来观察工具如何重排:
#include <stdio.h>
int main(void){int value=42; // 这个变量用于观察空格与缩进的统一结果
if(value>0){printf("value=%d\n",value);}return 0;}在项目根目录执行:
clang-format src/main.c预期输出:
#include <stdio.h>
int main(void) {
int value = 42; // 这个变量用于观察空格与缩进的统一结果
if (value > 0) {
printf("value=%d\n", value);
}
return 0;
}不带 -i 时,格式化结果只写到标准输出,不会改原文件。这适合先检查规则是否符合预期。
原地格式化并自动校验
确认规则后,可以让 clang-format 直接改写文件,再用只检查不改写的模式验证:
clang-format -i src/main.c
clang-format --dry-run --Werror src/main.c
printf '%s\n' "$?"预期输出:
0退出码为 0 表示格式检查通过。若文件不符合规则,--Werror 会让检查失败,适合放进 CI。它只判断格式,不替代编译、测试或静态分析。
团队使用时要控制版本和范围
不同 clang-format 大版本可能对同一规则产生细微差异,团队最好固定工具版本,至少固定主版本。CI 也应使用同一版本,否则本地格式化通过后,服务器仍可能重新判定为不一致。
格式化范围只覆盖团队维护的源码即可。第三方依赖、自动生成代码和构建目录通常应排除,否则会制造无意义的大量 diff。统一格式的目标不是“让工具改遍所有文件”,而是让仓库中的自有 C/C++ 代码始终能被同一份规则稳定重排。