C / C++ / 系统课时

用 clang-format 统一代码格式

用 clang-format 统一代码格式

多人协作时,手工约定缩进和括号风格很容易漂移。clang-format 可以把格式规则写进仓库,并用同一条命令在本地和 CI 中执行。本节会完成规则文件、格式化操作和可自动判定的校验流程。

学习目标

  • 能创建项目级 .clang-format 并理解常用规则
  • 能对单个 C 文件执行预览、原地格式化和校验
  • 能把格式检查接入提交或 CI 流程,避免风格反复变化

把规则放进仓库

clang-format 会从目标文件所在目录向父目录查找 .clang-format。因此通常把它放在项目根目录,并与源码一起提交。团队成员和 CI 使用同一份文件,格式规则才真正可复现。

下面是一份偏保守的项目级配置:

yaml
BasedOnStyle: LLVM
IndentWidth: 4
TabWidth: 4
UseTab: Never
ColumnLimit: 100
BreakBeforeBraces: Attach

这份配置以 LLVM 风格为基础,再覆盖缩进、制表符、行宽和大括号策略。配置文件本身不会修改代码,只有运行 clang-format 时才会生效;后续可用 --dry-run --Werror 验证源码是否已经符合规则。

先预览再修改

假设 src/main.c 当前内容如下。这里故意把多条语句挤在一起,用来观察工具如何重排:

c
#include <stdio.h>

int main(void){int value=42; // 这个变量用于观察空格与缩进的统一结果
if(value>0){printf("value=%d\n",value);}return 0;}

在项目根目录执行:

bash
clang-format src/main.c

预期输出:

c
#include <stdio.h>

int main(void) {
    int value = 42; // 这个变量用于观察空格与缩进的统一结果
    if (value > 0) {
        printf("value=%d\n", value);
    }
    return 0;
}

不带 -i 时,格式化结果只写到标准输出,不会改原文件。这适合先检查规则是否符合预期。

原地格式化并自动校验

确认规则后,可以让 clang-format 直接改写文件,再用只检查不改写的模式验证:

bash
clang-format -i src/main.c
clang-format --dry-run --Werror src/main.c
printf '%s\n' "$?"

预期输出:

text
0

退出码为 0 表示格式检查通过。若文件不符合规则,--Werror 会让检查失败,适合放进 CI。它只判断格式,不替代编译、测试或静态分析。

团队使用时要控制版本和范围

不同 clang-format 大版本可能对同一规则产生细微差异,团队最好固定工具版本,至少固定主版本。CI 也应使用同一版本,否则本地格式化通过后,服务器仍可能重新判定为不一致。

格式化范围只覆盖团队维护的源码即可。第三方依赖、自动生成代码和构建目录通常应排除,否则会制造无意义的大量 diff。统一格式的目标不是“让工具改遍所有文件”,而是让仓库中的自有 C/C++ 代码始终能被同一份规则稳定重排。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 clang-format 统一代码格式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通