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`	尾随注释对齐	行尾注释垂直对齐

对齐效果示例

连续赋值对齐：

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

连续声明对齐：

// 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语句单行：

// AllowShortIfStatementsOnASingleLine: Never
// 正确格式：
if (condition)
{
    action();
}

换行配置

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

大括号风格示例

Allman 风格：

// BreakBeforeBraces: Allman
void function()
{
    if (condition)
    {
        // 代码
    }
}

参数和装箱配置

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

参数格式化示例

禁止参数装箱效果：

// 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]`

包含文件优先级

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

排序效果：

// 按优先级排序的包含文件
#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