clang-format 配置规则说明

本文档详细说明项目中 .clang-format 文件的各项配置规则及其效果。

基本语言配置

配置项 当前值 说明 效果
Language Cpp 语言类型，也适用于C语言 使用C++/C语言的格式化规则
Standard Latest 使用最新的语言标准 支持最新的语法特性格式化
ColumnLimit 120 每行最大字符数 超过120字符自动换行

对齐配置

配置项 当前值 说明 示例
AccessModifierOffset -2 访问修饰符缩进 public: 相对类缩进-2个空格
AlignAfterOpenBracket Align 开括号后内容对齐 参数与开括号对齐
AlignConsecutiveAssignments true 连续赋值语句对齐 = 号垂直对齐
AlignConsecutiveDeclarations true 连续变量声明对齐 变量名垂直对齐
AlignConsecutiveMacros true 连续宏定义对齐 宏名垂直对齐
AlignEscapedNewlines Left 续行反斜杠对齐方式 反斜杠左对齐
AlignOperands true 操作数对齐 多行表达式操作数对齐
AlignTrailingComments true 尾随注释对齐 行尾注释垂直对齐

对齐效果示例

连续赋值对齐：

1
2
3
4
// AlignConsecutiveAssignments: true
int    x     = 10;
double value = 3.14;
char  *name  = "test";

连续声明对齐：

1
2
3
4
// AlignConsecutiveDeclarations: true
int        count;
double     ratio;
Button_t  *button;

单行限制配置

配置项 当前值 说明 效果
AllowShortBlocksOnASingleLine Never 禁止短代码块单行 if (x) { y = 1; } → 必须换行
AllowShortCaseLabelsOnASingleLine false 禁止短case标签单行 case语句必须换行
AllowShortFunctionsOnASingleLine None 禁止短函数单行 所有函数都必须换行
AllowShortIfStatementsOnASingleLine Never 禁止短if语句单行 if语句必须换行
AllowShortLoopsOnASingleLine false 禁止短循环单行 for/while循环必须换行

单行限制示例

禁止短if语句单行：

1
2
3
4
5
6
// AllowShortIfStatementsOnASingleLine: Never
// 正确格式：
if (condition)
{
    action();
}

换行配置

配置项 当前值 说明 效果
AlwaysBreakAfterDefinitionReturnType None 函数定义返回类型换行 返回类型和函数名同行
AlwaysBreakAfterReturnType None 函数声明返回类型换行 返回类型和函数名同行
AlwaysBreakBeforeMultilineStrings false 多行字符串前不换行 字符串紧跟赋值符
BreakBeforeBraces Allman 大括号换行风格 大括号独占一行
BreakBeforeBinaryOperators None 二元运算符换行位置 运算符在行末
BreakBeforeTernaryOperators false 三元运算符换行位置 ? 和 : 在行末
BreakStringLiterals true 允许字符串字面量换行 长字符串可以换行

大括号风格示例

Allman 风格：

1
2
3
4
5
6
7
8
// BreakBeforeBraces: Allman
void function()
{
    if (condition)
    {
        // 代码
    }
}

参数和装箱配置

配置项 当前值 说明 效果
AllowAllArgumentsOnNextLine false 禁止所有参数换到下一行 参数分行显示
AllowAllParametersOfDeclarationOnNextLine false 禁止所有参数换到下一行 函数参数分行显示
BinPackArguments false 禁止参数装箱 每个参数独占一行
BinPackParameters false 禁止参数装箱 每个参数独占一行

参数格式化示例

禁止参数装箱效果：

1
2
3
4
5
6
7
8
9
// BinPackArguments: false
function_call(
    argument1,
    argument2,
    argument3
);

// 而不是：
// function_call(argument1, argument2, argument3);

缩进配置

配置项 当前值 说明 效果
IndentWidth 4 缩进宽度 使用4个空格缩进
IndentCaseLabels true case标签缩进 case相对switch缩进
IndentWrappedFunctionNames true 换行函数名缩进 换行的函数名缩进
TabWidth 4 Tab宽度 Tab等于4个空格
UseTab Never 不使用Tab 始终使用空格

换行惩罚权重

配置项 当前值 说明 作用
PenaltyBreakBeforeFirstParameter 5 函数定义换行惩罚 降低函数参数换行倾向
PenaltyBreakBeforeFirstCallParameter 5 函数调用换行惩罚 降低函数调用换行倾向
PenaltyBreakAssignment 10 赋值换行惩罚 降低赋值运算符换行倾向
PenaltyExcessCharacter 100 超出字符惩罚 每个超出字符的惩罚值
PenaltyReturnTypeOnItsOwnLine 0 返回类型独行惩罚 不惩罚返回类型独行

其他格式化配置

配置项 当前值 说明 效果
PointerAlignment Right 指针星号对齐 char *ptr 星号靠近变量名
ReflowComments true 重新格式化注释 自动调整注释格式
SortIncludes true 排序包含文件 自动排序#include
MaxEmptyLinesToKeep 1 最大空行数 最多保留1个空行
KeepEmptyLinesAtTheStartOfBlocks false 块开始处不保留空行 { 后不允许空行

空格配置

配置项 当前值 说明 示例
SpaceAfterCStyleCast true C风格转换后加空格 (int) x
SpaceAfterLogicalNot false 逻辑非后不加空格 !condition
SpaceBeforeAssignmentOperators true 赋值运算符前加空格 x = y
SpaceBeforeParens ControlStatements 控制语句圆括号前加空格 if (condition)
SpacesBeforeTrailingComments 1 尾随注释前空格数 code; // comment
SpacesInParentheses false 圆括号内不加空格 function(arg)
SpacesInSquareBrackets false 方括号内不加空格 array[index]

包含文件优先级

1
2
3
4
5
6
7
8
9
10
11
IncludeCategories:
  - Regex: '"*PlatformIO.h"' # 优先级: -5 (最高)
    Priority: -5
  - Regex: '"*TextIOTypes.h"' # 优先级: -4
    Priority: -4
  - Regex: "<[Ww]indows.h>" # 优先级: -3
    Priority: -3
  - Regex: '<*\/.h>' # 优先级: -2 (系统头文件)
    Priority: -2
  - Regex: '"*\/.h"' # 优先级: 1 (用户头文件)
    Priority: 1

排序效果：

1
2
3
4
5
6
7
8
// 按优先级排序的包含文件
#include "PlatformIO.h"      // -5
#include "TextIOTypes.h"   // -4
#include <Windows.h>        // -3
#include <stdio.h>          // -2
#include <stdlib.h>         // -2
#include "button.h"         // 1
#include "config.h"         // 1

项目适配说明

当前配置针对嵌入式C项目优化：

  • 可读性优先: 大括号独占一行，参数分行显示
  • 一致性: 自动对齐声明、赋值、注释
  • 紧凑性: 120列限制，适合代码审查
  • 规范性: 统一的空格、缩进规则
  • 维护性: 自动排序包含文件，重新格式化注释

这套配置确保代码风格统一，提高团队协作效率。