第四章：编码规范——C/C++编码规范制定、静态代码检查工具、代码格式化与注释要求

编码规范这事儿，我做了十几年嵌入式，见过太多因为代码风格混乱导致的线上事故。说实话，很多团队觉得规范是束缚，但在我看来，规范其实是保护伞。你想想看，一个嵌入式项目动辄几十万行代码，没有统一的规矩，后期维护就是噩梦。

4.1 编码规范制定：别让风格成为隐患

我参与过的第一个大型项目，团队七个人，代码风格七种。有人喜欢匈牙利命名法，有人用下划线，有人缩进用空格，有人用Tab。结果呢？代码审查时，一半时间在争论格式问题。后来我痛定思痛，开始认真搞编码规范。

4.1.1 命名规范：一眼看懂变量用途

我个人习惯用下划线命名法（snake_case）做嵌入式C代码。为什么？因为C语言本身是大小写敏感的，而嵌入式代码经常要和硬件寄存器打交道，寄存器名字通常是大写加下划线。混用容易看花眼。

核心原则：命名要自解释，不要用a、b、c这种单字母变量（循环变量i、j除外）。 
// 不好的命名
int a;          // 什么鬼？
int cnt;        // 计数什么？
int flag;       // 什么标志？

// 好的命名
int motor_speed_rpm;        // 一目了然：电机转速，单位RPM
int adc_sample_count;       // ADC采样次数
uint8_t system_error_flag;  // 系统错误标志位

我在项目中遇到过最坑的一次：一个同事用temp命名了三个不同作用的变量——临时温度、临时缓冲区、临时状态。调试了三天才发现是变量覆盖了。从那以后，我要求团队必须用有意义的全名，宁可长一点，不能模糊。

4.1.2 缩进与括号：统一才能协作

缩进用空格还是Tab？我的建议是：用空格，4个空格。为什么？因为不同编辑器对Tab的解释不一样。有的当2个空格，有的当4个，有的当8个。你想想看，代码在不同人电脑上显示得七扭八歪，还怎么合作？

括号风格我推荐Allman风格（括号独占一行），尤其是在嵌入式C中。因为嵌入式代码经常有很深的嵌套，括号独占一行能让代码结构更清晰。

// Allman风格（推荐）
if (sensor_value > threshold)
{
    motor_control(SPEED_UP);
    delay_ms(10);
}
else
{
    motor_control(SLOW_DOWN);
}

// K&R风格（也可以，但要统一）
if (sensor_value > threshold) {
    motor_control(SPEED_UP);
    delay_ms(10);
} else {
    motor_control(SLOW_DOWN);
}
注意：千万不要混用！我见过一个项目，同一个文件里三种括号风格都有。代码审查时，光对齐括号就花了半小时。统一风格，从第一天做起。

4.1.3 文件组织：模块化是王道

嵌入式项目通常按功能模块组织文件。我个人习惯这样分：

目录/文件 内容 示例
drv_xxx.c/h 硬件驱动层 drv_uart.c, drv_i2c.c
hal_xxx.c/h 硬件抽象层 hal_timer.c, hal_gpio.c
app_xxx.c/h 应用逻辑层 app_sensor.c, app_control.c
lib_xxx.c/h 通用库函数 lib_math.c, lib_crc.c

每个.c文件对应一个.h文件。头文件里只放接口声明，实现细节藏在.c里。这叫信息隐藏，说白了就是「你只管用，别管我怎么实现的」。

4.2 静态代码检查工具：让机器帮你找茬

人眼检查代码，总有看漏的时候。我记得有一次，一个数组越界的bug在生产线上跑了三个月才被发现。从那以后，我坚持所有代码必须过静态检查。

4.2.1 常用工具对比

工具 适用语言 特点 我的评价
PC-Lint C/C++ 老牌工具，规则全面 配置复杂，但查得最细
Cppcheck C/C++ 开源免费，轻量级 适合日常快速检查
Clang-Tidy C/C++ LLVM家族，现代C++支持好 我目前的主力工具
Coverity C/C++/Java 商业工具，深度分析 贵，但值得

4.2.2 实战：用Cppcheck做快速检查

我建议团队在每次提交代码前，先跑一遍Cppcheck。配置很简单：

# 基本检查
cppcheck --enable=all --suppress=missingIncludeSystem ./src/

# 更严格的检查（适合关键模块）
cppcheck --enable=all --std=c99 --suppress=missingIncludeSystem \
         --inconclusive --check-config ./src/

为什么会推荐Cppcheck？因为它能发现一些很隐蔽的问题。比如：

  • 未初始化的变量
  • 内存泄漏
  • 空指针解引用
  • 数组越界
  • 逻辑错误（如if条件永远为真）
小技巧：把静态检查集成到CI/CD流水线中。我之前的项目，每次git push都会自动触发检查。检查不通过，代码不允许合并。刚开始大家觉得烦，后来发现线上bug减少了70%。

4.2.3 避坑指南：静态检查不是万能药

我曾经遇到过一件事：一个同事觉得静态检查过了，代码就安全了。结果呢？逻辑错误静态检查是查不出来的。比如：

// 静态检查不会报错，但逻辑有问题
if (temperature > 100)
{
    fan_speed = HIGH;
}
else if (temperature > 50)
{
    fan_speed = MEDIUM;
}
else if (temperature > 0)
{
    fan_speed = LOW;
}
// 问题：温度在0-50之间时，fan_speed被设置成LOW
// 但温度低于0时呢？fan_speed没有初始化！

静态检查能发现fan_speed未初始化，但发现不了「温度低于0时应该怎么处理」这个逻辑漏洞。所以，静态检查是工具，不是替代品。代码审查和单元测试，一个都不能少。

4.3 代码格式化：让代码像印刷品一样整齐

代码格式化这事儿，我建议用工具自动完成。手动调整缩进和对齐，既浪费时间又容易出错。我见过有人花一下午调整代码对齐，结果第二天需求变更，全部白干。

4.3.1 推荐工具：Clang-Format

Clang-Format是LLVM项目的一部分，支持C/C++/Java/JavaScript等多种语言。配置一个.clang-format文件，团队统一使用，代码风格自动统一。

# .clang-format 配置文件示例
BasedOnStyle: Google
IndentWidth: 4
UseTab: Never
BreakBeforeBraces: Allman
AllowShortIfStatementsOnASingleLine: false
ColumnLimit: 100

我个人习惯用Google风格做基础，然后微调。为什么选Google风格？因为它的规则清晰，社区认可度高。新同事来了，看一眼配置就知道规矩。

4.3.2 集成到编辑器

我建议把格式化工具集成到开发环境中。比如：

  • VS Code：安装C/C++扩展，配置保存时自动格式化
  • CLion：内置Clang-Format支持，一键格式化
  • Vim：配置clang-format插件，:ClangFormat即可

你想想看，每次保存代码，格式自动调整好。缩进、空格、换行全部统一。代码审查时，大家只关注逻辑，不纠结格式。多省心！

注意：格式化工具不要改代码逻辑。我遇到过Clang-Format把a++改成++a的情况（在某些配置下）。所以，格式化后一定要做一次代码审查，确保逻辑没变。

4.4 注释要求：写给人看的，不是写给机器看的

注释这事儿，我踩过不少坑。刚开始写代码时，我觉得注释越多越好。后来发现，废话注释比没有注释更可怕。比如：

// 坏注释：废话连篇
int a = 0;  // 把a赋值为0
int b = 1;  // 把b赋值为1

// 好注释：解释为什么
int motor_speed = 0;  // 电机初始速度为0，防止上电误转

4.4.1 注释写什么

我个人总结了三类必须写注释的场景：

  1. 为什么这么做：代码逻辑可能看起来奇怪，但背后有原因。比如「这里用while循环而不是for循环，因为要处理中断重入」。
  2. 边界条件：数组长度、超时时间、阈值等。比如「缓冲区大小1024字节，最大报文长度1000字节，留24字节给协议头」。
  3. 硬件相关：寄存器地址、时序要求、硬件限制。比如「等待至少10ms，因为传感器上电需要稳定时间」。

4.4.2 注释怎么写

我推荐用Doxygen风格的注释，方便生成文档。格式统一，可读性强。

/**
 * @brief 初始化UART外设
 * @param baudrate 波特率，支持9600、19200、115200
 * @param data_bits 数据位，可选5/6/7/8
 * @return 0表示成功，-1表示参数错误
 * 
 * @note 调用此函数前，请确保GPIO已配置为UART功能
 * @warning 波特率超过115200时，需要检查硬件是否支持
 */
int uart_init(uint32_t baudrate, uint8_t data_bits);

为什么要用Doxygen？因为可以自动生成API文档。我之前的项目，每次发布版本时，用Doxygen生成一份PDF文档，给测试和硬件团队看。省去了反复口头沟通的麻烦。

4.4.3 注释的禁忌

我曾经在代码审查中看到这样的注释：

// 以下代码由张三编写，2023-01-01
// 李四修改，2023-06-01
// 王五又修改，2023-12-01
// 赵六再修改，2024-03-01
// ...（此处省略20行修改记录）

这种注释，说白了就是垃圾。修改记录应该用版本控制工具（Git）管理，而不是写在代码里。注释只应该解释「代码是什么、为什么这么做」，不要记录「谁在什么时候做了什么」。

核心原则：好的注释，是告诉读者「代码没有说出来的事情」。如果代码本身已经足够清晰，注释就是多余的。

4.5 总结：规范是团队的共同语言

编码规范、静态检查、格式化、注释，这四件事做好了，团队的代码质量会有质的提升。我见过太多团队，前期不重视规范，后期维护成本翻倍。你想想看，一个项目做三年，前半年把规范定好，后面两年半都在受益。这笔账，怎么算都划算。

最后说一句：规范不是死的。随着项目发展，规范也需要迭代。我建议每个季度做一次规范回顾，看看哪些规则需要调整。但记住，一旦定下来，就要严格执行。没有执行力的规范，就是一张废纸。

← 上一章 📖 返回目录 下一章 →