clang-format 的配置文件叫 .clang-format，格式是 YAML。
它的设计理念是：
先继承一种已有风格（Google、LLVM、Microsoft...），然后只修改你关心的选项。
一般不要从零开始写，而是：
BasedOnStyle: Google
然后覆盖需要修改的配置。
⸻
一、一个完整的模板（推荐现代 C++ 项目）
这是我比较推荐的一套，介于 Google 和 LLVM 之间，适合 Linux/CUDA/HPC/C++ 项目。
yaml
Language: Cpp
# 基础风格
BasedOnStyle: Google
# 缩进
IndentWidth: 4
ContinuationIndentWidth: 4
TabWidth: 4
UseTab: Never
# 一行最大长度
ColumnLimit: 100
# 大括号
BreakBeforeBraces: Attach
# 指针和引用
PointerAlignment: Left
ReferenceAlignment: Left
# 空格
SpaceBeforeParens: ControlStatements
SpaceInEmptyParentheses: false
SpacesInAngles: Never
# include
SortIncludes: CaseSensitive
IncludeBlocks: Preserve
# 命名空间
NamespaceIndentation: None
# switch
IndentCaseLabels: true
# 类访问权限
AccessModifierOffset: -4
# 连续声明
AlignConsecutiveDeclarations: true
AlignConsecutiveAssignments: true
# 参数换行
BinPackArguments: false
BinPackParameters: false
# 构造函数初始化列表
BreakConstructorInitializers: BeforeComma
# Lambda
AllowShortLambdasOnASingleLine: Inline
# if
AllowShortIfStatementsOnASingleLine: Never
# while
AllowShortLoopsOnASingleLine: false
# 函数
AllowShortFunctionsOnASingleLine: Empty
# namespace结束注释
FixNamespaceComments: true
# C++11列表初始化
Cpp11BracedListStyle: true
# 注释
ReflowComments: true
# 空行
KeepEmptyLinesAtTheStartOfBlocks: false
MaxEmptyLinesToKeep: 1
# 自动识别
Standard: Latest这份配置已经可以覆盖 90% 以上的项目。
⸻
二、配置项详解
- BasedOnStyle
最重要的一项。
BasedOnStyle: Google
可选：
LLVM
Chromium
Mozilla
Microsoft
GNU
WebKit
例如：
BasedOnStyle: LLVM
或者
BasedOnStyle: Microsoft
一般推荐：
⸻
- IndentWidth
缩进。
IndentWidth: 4
结果：
if (ok) {
foo();
}
如果：
IndentWidth: 2
就是
if (ok) {
foo();
}
⸻
- ColumnLimit
每行最大长度。
ColumnLimit: 100
超过会自动换行。
例如：
foo(a,b,c,d,e,f,g,h,i,j,k);
变成：
foo(a,
b,
c,
d,
e);
推荐：
100
Google：
80
LLVM：
80
现代显示器一般推荐 100 或 120。
⸻
- BreakBeforeBraces
大括号风格。
最常见：
BreakBeforeBraces: Attach
效果：
if (...) {
}
如果：
BreakBeforeBraces: Allman
变成
if (...)
{
}
还有：
Linux
Mozilla
GNU
WebKit
Custom
⸻
- PointerAlignment
很多团队争论最多的问题。
Left
PointerAlignment: Left
得到
int* p;
⸻
Right
PointerAlignment: Right
得到
int *p;
⸻
Middle
PointerAlignment: Middle
得到
int * p;
Google：
Left
Linux：
Right
⸻
- ReferenceAlignment
和指针一样。
int& a;
还是
int &a;
推荐：
ReferenceAlignment: Left
⸻
- NamespaceIndentation
例如：
namespace foo {
class A {};
}
如果：
NamespaceIndentation: None
保持：
namespace foo {
class A {};
}
如果：
NamespaceIndentation: All
就是
namespace foo {
class A {};
}
LLVM 和 Google 一般都不缩进 namespace。
⸻
- BinPackArguments
控制函数参数是否尽量塞在同一行。
如果：
BinPackArguments: true
可能得到：
foo(a, b,
c, d,
e);
如果：
BinPackArguments: false
会变成：
foo(
a,
b,
c,
d);
现代代码很多团队喜欢：
false
可读性更高。
⸻
- AlignConsecutiveDeclarations
例如：
int a;
double b;
float c;
如果：
AlignConsecutiveDeclarations: true
变量会自动对齐。
⸻
- SortIncludes
例如：
vector
iostream
algorithm
自动变成
algorithm
iostream
vector
推荐：
SortIncludes: CaseSensitive
也可以：
SortIncludes: Never
如果项目对头文件顺序有特殊要求。
⸻
- IncludeBlocks
例如：
#include
#include "a.h"
#include "b.h"
如果：
IncludeBlocks: Merge
会合并。
推荐：
IncludeBlocks: Preserve
保留人工分组。
⸻
- AllowShortFunctionsOnASingleLine
例如：
int f() { return 0; }
如果：
AllowShortFunctionsOnASingleLine: None
会展开：
int f() {
return 0;
}
推荐：
Empty
只有空函数保留一行。
⸻
三、如何生成默认配置
如果已经安装了 clang-format，可以直接导出某种风格的完整配置：
clang-format -style=google -dump-config > .clang-format
或者：
clang-format -style=llvm -dump-config > .clang-format
生成的文件通常有 250～350 行（不同版本略有差异），包含几乎所有可配置项，非常适合作为参考。你只需要删除不关心的选项，保留需要修改的部分即可。
⸻
四、我推荐的模板（适合现代 C++）
如果是新项目，我建议采用以下原则：
- 基于 Google 风格，保证团队一致性。
- 4 空格缩进，适合大多数 C++ 项目。
- 100 列行宽，兼顾可读性和现代宽屏显示器。
- PointerAlignment: Left、ReferenceAlignment: Left，与 Google 风格一致。
- 保留 #include 分组，避免自动打乱逻辑分层。
- 关闭参数打包（BinPackArguments: false、BinPackParameters: false），让长参数列表按行排列，更易于阅读和维护。
- 限制空行数量，保持代码紧凑但不过于拥挤。
这套配置比较适合你之前讨论过的 Linux、CUDA/HIP、高性能计算和现代 C++ 项目，也便于与 clang-tidy 配合使用。