C语言这门语言有个特点：语法简单到你几天就能上手，但代码能不能让人舒心维护，几乎全看写代码的人有没有一套稳定的编写规范和注释规范。我做嵌入式开发这些年，写过也接手过各种规模的C项目，对此深有体会——一个功能再完整的代码库，如果风格混乱、注释缺席、命名随意，后续维护成本会成倍翻，严重的时候甚至没人愿意去动它。
这篇文章不打算复述教科书里的纪律条款，而是想结合我自己在实际项目中踩过、填过的坑，把C语言代码的编写规范和注释规范里那些真正影响项目质量的细节逐一讲清楚。不管你是刚开始学C的在校生，还是在团队里负责代码评审的开发者，下面这些经验应该都能直接派上用场。
1. 明明能跑的代码，为什么要给规范较真
1.1 乱代码库的真实成本
我接手过几个没有规范约束的嵌入式项目，那种痛苦到现在都印象深刻。有一个固件工程，单文件里塞了将近三千行代码，缩进混用tab和空格，变量名从a、b、tmp1排到tmp9。函数名也是五花八门，有deal()、handle()、do_it()，乍一看都以为是在做不同的事，翻到定义才发现全是同一套流程里的不同环节。
最折磨人的还不是这些，而是注释。文件开头没有模块说明，函数前面没有接口描述，行内注释全是“// 这里处理一下”这类废话。我为了确认一个缓冲区到底由谁分配、由谁释放，整整追了两天调用链，最后发现关键逻辑藏在一个没有被任何注释标注的静态函数里。
后来我复盘这次维护经历，算了一笔账：一段正常应该两小时改完的代码，因为阅读成本高，硬是拖到两天。这就是代码规范缺失的直接代价——它不直接影响程序能不能跑，但直接影响人愿意不愿意改、敢不敢改。
1.2 规范要解决的三个核心问题
既然谈到C语言代码的编写规范，就要先把“为什么要有规范”这件事说透。在我看来，规范不是为了限制个人风格，它解决的是三个很现实的问题。
第一是降低阅读成本。代码首先是给人读的，然后才给机器执行。统一命名、统一排版之后，任何人接手一个文件，不需要先翻译作者的“个人方言”，打开就能进入业务逻辑。
第二是减少低级失误。别觉得规范跟bug没关系，命名语义不清、函数职责混乱、缩进错乱，这些都会间接制造问题。比如两个相似命名的变量，在复杂表达式里就很容易被误用；函数过长的时候，局部变量作用域也会跟着变复杂，出现意外覆盖的情况并不少见。
第三是提升协作效率。多人开发同一个固件或者中间件项目时，代码评审、模块交接、合并冲突处理都会因为规范而顺畅很多。团队统一了格式之后，评审时大家只需要关注逻辑正不正确、边界处不处理得到，而不是花时间争论“这个括号到底该放在哪一行”。
2. 命名规范：让变量、函数、宏各归其位
2.1 变量命名：见名知意比压缩行数重要
变量是代码里出现频率最高的东西，它的命名质量直接决定阅读体验。我的习惯是统一用“名词”来命名变量，用完整单词或者业界公认缩写，坚决避免用a、b这种单字母，除非是在极短循环里充当索引变量。
// 不推荐 int t; // 运行时长？ int n; // 数量？ // 推荐 int run_duration_ms; int file_count;有朋友可能会说，单字母变量在局部作用域也能看懂。这话在十行代码内成立，一旦函数超过五十行，再看n就要靠猜了。尤其是代码经过多次修改之后，原本n表示“数量”，后来又被复用成“偏移量”，这种变量基本就是炸弹。
变量的前缀也可以约定一套习惯。比如用g_表示全局变量，用s_表示static变量，指针变量加p_前缀等。这些约定不强求统一，但最好在项目文档里写明。
2.2 函数命名：动词开头，动作完整
函数名应该表达“它做了什么”，而不是“它怎么做的”。C语言里更通用的写法是“动词+宾语”，比如read_config_file()、calculate_crc()、send_packet()、release_memory()，一眼就能看出函数意图。
对比下面两个命名：
// 不清晰 void handle_package(void); // 拆细之后 void parse_http_packet(void); void validate_packet_length(void); void forward_packet_to_queue(void);如果一个函数很难命名，多半是它做了太多事。命名困难本身就是设计上的警示信号，这时候应该先拆函数，而不是硬凑一个模糊的名字。团队里函数命名风格要保持一致，我推荐统一用lower_snake_case，也就是小写字母加下划线，这在C项目里是接受度很高的写法。
2.3 宏、常量与类型名的三等分约定
C语言中宏、常量、自定义类型这三样东西容易混在一起，命名上不做区分的话，代码看起来就是一团。我的建议是给它们各自一套风格。
宏定义建议全部大写加下划线：
#define BUFFER_SIZE 1024 #define MAX_CONNECTIONS 16 #define IS_POWER_OF_TWO(x) (((x) & ((x) - 1)) == 0)常量用const限定符，命名上可以大写，也可以用小写前缀风格，团队内部统一即可：
const int kMaxRetryCount = 3; const double kPi = 3.1415926535;类型别名建议在末尾加_t，这是很多C项目约定俗成的做法，能直接跟变量名区分开：
typedef unsigned char byte_t; typedef struct { ... } packet_t; typedef void (*callback_fn_t)(int event);把这三类名字的风格区分开之后，阅读代码时不用看定义，光看名字就能判断出它是什么身份，节省的脑力在大型工程里非常可观。
2.4 文件命名与头文件保护
文件命名要跟模块职责一致，常见实践是modulename.c和modulename.h成对出现。比如uart_driver.c对应uart_driver.h，log_manager.c对应log_manager.h。文件名里不要混用大写和连字符，统一用小写字母加下划线，这样在大小写敏感的编译环境和各类版本控制工具里都能避开不必要的坑。
头文件的保护宏要跟文件路径关联，避免不同模块的头文件重名冲突。比如uart_driver.h位于app/drivers/目录下，可以这样写：
#ifndef APP_DRIVERS_UART_DRIVER_H #define APP_DRIVERS_UART_DRIVER_H #endif /* APP_DRIVERS_UART_DRIVER_H */别小看这个细节，一旦工程里出现两个同名头文件，而且保护宏又恰好一样，包含顺序就会决定编译能否通过，这种问题排查起来非常耗时。
3. 排版与缩进：把代码当成版面来设计
3.1 缩进宽度与风格选择
C语言社区流传较广的缩进风格有好几种，K&R风格、Allman风格、GNU风格。GNU风格因为它的特殊缩进方式让很多人头疼，实际项目里大多数团队用的是K&R或Allman中的一种。
我一直坚持缩进宽度固定为4个空格，不用tab字符来缩进。tab在不同编辑器里的显示宽度不一样，还容易在对齐时产生错位。把编辑器配置成“tab自动替换为4个空格”，再用clang-format统一格式，基本能避免这类“格式撕扯”。
K&R风格下的大括号写法是这样的：
if (condition) { do_something(); do_another(); } else { handle_failure(); }Allman风格下的大括号独立换行：
if (condition) { do_something(); do_another(); } else { handle_failure(); }两种风格本身没有对错，关键是整个工程选一种并贯彻到底。见过不少项目混着两种风格，每次改代码处理格式比写逻辑还耗时间，这种内耗毫无必要的。
3.2 大括号的书写和省略禁区
大括号的书写直接影响代码块边界的识别。我的建议是：函数体的大括号独立一行或跟随函数名末尾都行，但控制语句的大括号必须清晰表示嵌套层级，整个项目统一即可。
这里强烈建议：不要省略单语句块的大括号。
// 不推荐 if (len > 0) send_packet(len); // 推荐 if (len > 0) { send_packet(len); }省略大括号在代码评审里是高频问题。为什么这么在意这件事？因为后续维护者很容易在if下面继续加第二行代码，然后忘记补大括号，于是第二行变成了无条件执行。这类bug在真实项目里出现过太多次，只要形成“大括号必写”的习惯，就能从根本上避免。
3.3 空格、空行与分块艺术
空格的使用规则虽然琐碎，但对可读性的提升很直接。我一般遵循这样几个原则：
- 二元操作符两侧加空格：
sum = a + b; - 逗号后面加空格：
void func(int a, int b); - 关键字和左括号之间加空格：
if (x > 0) - 函数名和左括号之间不加空格：
foo(1) - 指针的星号贴合变量名：
int *ptr; - 结构体成员的箭头前后不加空格：
node->next
空行的作用是把逻辑块分隔开。函数内可以根据处理阶段分块，每块之间留一个空行，让读者在视觉上先看到段落结构。我发现很多开发者为了省空间把代码挤在一起，其实空行不是在浪费版面，而是给阅读者留出呼吸感。
3.4 行宽为什么值得较真
代码行建议控制在80个字符左右。这个数字来自早期终端行宽的物理限制，到今天虽然屏幕变宽了，但控制行宽仍然有价值：不需要频繁横向滚动，评审时也能在一个视野内看完一整行。
当一行超过80字符时，常见的拆行方式是在操作符前换行，续行内容再缩进一层：
int result = long_function_name(argument_one, argument_two, argument_three, argument_four);有些团队会把限制放宽到100或120字符，但并不是越宽越好。一旦超过120字符，横向阅读负担明显增加。建议在团队文档里定一个明确值，然后用工具校验，不要靠“肉眼目测”。
4. 函数级规范：短小、单一、边界清晰
4.1 函数拆分的基本原则
函数长度没有一个绝对的硬性上限，但我的经验是单个函数尽量控制在80行以内，超过这个阈值就要回头想想能不能拆分。切分函数的依据不是“能不能编译”，而是“职责是否单一”。
看一个反面例子，这个init_device()做了三件事：读配置、解析配置、初始化硬件。
// 不推荐的写法 void init_device(void) { FILE *fp = fopen("config.ini", "r"); if (fp == NULL) { ... } ... parse_config_line(...); ... register_interrupt_handler(...); ... }拆成三个函数之后，结构清晰很多：
static config_data_t load_config(const char *path); static void parse_config(config_data_t *cfg); static void init_hardware(const config_data_t *cfg); void device_setup(void) { config_data_t cfg = load_config("config.ini"); parse_config(&cfg); init_hardware(&cfg); }函数短小之后，单元测试写起来也会容易，每个小函数可以独立验证。很多朋友说“函数拆细了调用开销变大”，这在现代编译器面前基本不是问题，内联优化早就考虑过这些了。可读性带来的收益，远比那点性能开销值得。
4.2 参数数量与结构体封装
函数参数最好不要超过5个。参数太多，调用方很难记住顺序，极易写错。如果确实需要大量参数，就封装到一个结构体里：
typedef struct { const char *host; int port; int timeout_ms; int retry_count; } connect_params_t; int network_connect(const connect_params_t *params);把参数包成结构体还有个额外好处：后续新增参数时，不需要改函数签名，只需要扩展结构体字段，对调用方的影响大幅降低。这在维护长期稳定的对外接口时尤其重要。
4.3 错误码与返回值统一约定
返回值是C里面最容易被用乱的地方。有的函数返回0表示成功，有的返回1表示成功，有的返回NULL表示失败，混着用会让调用方处于猜谜状态。我比较常用的约定是：返回0表示成功，非0表示不同的错误码，错误码用枚举定义清楚：
typedef enum { ERR_NONE = 0, ERR_INVALID_ARG, ERR_TIMEOUT, ERR_NO_MEMORY, ERR_BUSY } err_code_t; err_code_t packet_send(const packet_t *pkt);这样调用方就能统一写if (ret != ERR_NONE)来判断成败，不需要去猜返回值代表什么。涉及返回指针的接口，要提前约定好内存谁分配、谁释放，避免泄露。
5. 注释规范：解释为什么，而不是复述做什么
5.1 注释的存在条件
注释不是越多越好，它应该在几个特定场合出现：解释“为什么”、记录“约束条件”、说明“算法思路”、标注“待处理问题”。
如果代码本身已经表达了“做什么”，就没有必要用注释复述一遍。下面这种注释就是在浪费版面：
// 发送数据 send_data();真正有用的注释长这样：
/* 这里不能直接用 memcpy， * 因为 src 和 dst 指向的数据区可能出现重叠， * 所以要用 memmove。 */ memmove(dst, src, len);它补充了代码本身没有表达的信息，解释了背后的选择和可能踩到的坑。这才是注释的核心价值。
5.2 文件头注释模板
每个源文件建议在开头放一段文件头注释，说明文件用途、所属模块，以及一些需要注意的约定。作者和修改历史可以交给版本管理工具维护，但文件头至少把“这个文件是干什么的”说清楚。
我自己常用的模板：
/** * @file uart_driver.c * @brief 串口驱动实现，提供初始化、发送、接收接口 * @remark 依赖硬件抽象层提供的寄存器读写函数 */头文件的注释稍有不同，重点要说明对外接口和使用约定：
/** * @file uart_driver.h * @brief 串口驱动对外接口 * @note 所有接口不保证线程安全，调用方需自行加锁 */这里特别提一下@note字段，它能把很多容易踩的坑直接提示给使用方。比如“不保证线程安全”“不能在中断上下文调用”“需要先初始化才能使用”，这些写在头文件注释里，比让调用方去读实现代码省力得多。
5.3 函数注释：说明意图和使用边界
函数级注释应该写清楚功能、参数含义、返回值含义，以及需要特别注意的前置条件。参考写法：
/** * @brief 解析命令行参数 * @param argc 参数个数 * @param argv 参数数组 * @param out_config 解析结果，不能为 NULL * @return ERR_NONE 表示成功，否则返回对应错误码 * @note 本函数内部会分配字符串资源， * 调用方需要通过 xxx_free() 释放 */ int parse_args(int argc, char *argv[], app_config_t *out_config);这段注释的关键点是：它在告诉调用方“怎么用、边界在哪、坑在哪”，而不是重复函数内部的步骤。
5.4 行内注释与特殊标注
行内注释主要用于解释比较绕的算法、位运算、状态机跳转等逻辑。比如状态机判断：
// 只有处于 IDLE 状态且收到启动事件，才允许进入 RUNNING 状态 if (state == STATE_IDLE && event == EVENT_START) { state = STATE_RUNNING; }对于位运算这种写出来很晦涩的操作，建议拆成宏并配上注释：
#define FLAG_SET(mask, bit) ((mask) |= ((uint32_t)1U << (bit))) #define FLAG_CLR(mask, bit) ((mask) &= ~((uint32_t)1U << (bit))) #define FLAG_IS_SET(mask, bit) (((mask) & ((uint32_t)1U << (bit))) != 0U)代码里经常会遇到“这块逻辑还没写完”“这个版本先这样但以后要改”的情况，建议使用统一标注前缀：
TODO：表示之后需要补全的功能或优化点FIXME：表示已知问题，需要修复XXX：表示代码虽然能跑，但实现方式可疑，需要重新审视
举例：
/* TODO: 当前用线性查找，数据量上来之后改用哈希表 */ int find_user_by_id(int uid) { ... } /* FIXME: 当前实现存在缓冲区溢出风险，需要尽快替换 */ char *strdup_new(const char *s) { ... }很多团队的CI脚本会扫描残留的TODO/FIXME，确保这些问题不会无声无息地混进发布版本。
6. 常见注释反模式：这些坑我几乎每个项目都见过
6.1 注释掉代码的清理原则
“把暂时不用的代码注释掉而不是删除”这个习惯，几乎在每个项目里都能见到。被注释掉的代码不仅让文件变得臃肿，还会对后来人形成误导，让人误以为这段逻辑还在起作用。
如果确实需要保留某段代码的历史版本，应该交给版本控制工具去解决。代码库不是备忘录，注释里保留大段旧逻辑，本质上是在给未来的维护者埋雷。我的经验是：一段代码被注释掉超过一个开发周期，就彻底删除，需要的时候去git历史里找。
6.2 显而易见的注释都是噪音
写注释的时候，有必要在落笔前问自己一句：这条注释提供的信息，是代码本身没有的吗？如果答案是“没有”，那就不写。
// 循环打印数组 for (int i = 0; i < n; i++) { printf("%d\n", arr[i]); }这种注释就是典型的噪音。但如果循环条件本身有额外语义，加个说明就很重要：
// 从尾部向前遍历，遇到第一个小于阈值的元素就停止 for (int i = n - 1; i >= 0 && arr[i] >= threshold; i--) { ... }判断注释质量的简单标准只有一个：删掉这条注释之后，代码会不会变得更难理解。如果不会，它就不应该存在。
6.3 用工具守住规范，别靠自觉
最后想说一点：只靠口头约定是守不住规范的，一定要让工具参与进来。C语言项目里常用的格式化工具是clang-format，静态检查工具可以选clang-tidy或cppcheck。把这些工具集成到构建流程或CI环境中，代码不合规直接构建失败，这是最有效的办法。
clang-format的配置文件.clang-format放在仓库根目录，几个关键项：
BasedOnStyle: LLVM IndentWidth: 4 UseTab: Never ColumnLimit: 80 PointerAlignment: Right BreakBeforeBraces: Allman配置定下来之后，团队评审时只需要关注逻辑正确性，格式问题全部交给工具处理。开发体验其实是提升的，而不是被格式约束的。
上个月我在某个项目里清理了一批被注释掉的初始化代码，整个模块文件的体积直接缩了三分之一，原本很容易出错的加载流程瞬间清晰了。那次之后我给自己定了条规矩：凡是注释掉的代码超过一个版本周期，坚决删除。规范这个东西，最终维护的是人与人之间的协作成本。C语言的语法可以靠几本书学完，但代码的编写规范和注释规范，只能依靠真实项目里一次次糟糕体验和认真反思慢慢沉淀。希望这些细则和模板能在你的项目里派上用场，也欢迎在实践中遇到问题的一起交流。
