头文件编写规范：头文件卫士、extern声明、内联函数、宏定义规范
头文件这东西，看着简单，写起来全是坑。我见过太多项目因为头文件没写好，编译报错几百行，查半天发现就是少了个头文件卫士。今天咱们就把头文件的几个核心规范捋清楚。
头文件卫士——你的第一道防线
说白了，头文件卫士就是为了防止同一个头文件被重复包含。你想想看，如果a.h包含了b.h，c.h也包含了b.h，然后某个源文件同时包含了a.h和c.h，那b.h里的内容就被定义了两次——编译器直接报重定义错误。
标准写法：
#ifndef __MY_HEADER_H__
#define __MY_HEADER_H__
/* 头文件内容 */
#endif /* __MY_HEADER_H__ */我个人习惯用宏名跟文件名对应，比如头文件叫uart_driver.h，宏名就用__UART_DRIVER_H__。这样一眼就能看出来是哪个文件。
小技巧：有些编译器支持#pragma once，写法更简洁。但我在跨平台项目里吃过亏——不是所有编译器都认这个。所以我的建议是：老老实实用#ifndef，兼容性最好。
extern声明——让变量跨文件可见
全局变量在嵌入式项目里很常见，但怎么声明才规范？我见过新手直接在头文件里写int g_counter;，结果每个包含这个头文件的源文件都定义了一个g_counter——链接的时候直接报multiple definition。
正确的做法是：
/* 在头文件中声明 */
extern int g_counter;
/* 在某个.c文件中定义 */
int g_counter = 0;extern只是告诉编译器：「这个变量在别处定义了，你先别报错」。真正分配内存的只有那个.c文件里的定义。
注意：全局变量能少用就少用。我曾经在一个项目里追了一个星期的bug，最后发现是两个模块通过全局变量互相干扰。能用函数传参就别用全局变量，这是血的教训。
内联函数——性能与代码体积的平衡
内联函数的好处是省去了函数调用的开销，适合那些调用频繁但代码量很小的函数。比如一个读取寄存器状态的函数：
static inline uint32_t read_reg(volatile uint32_t *addr)
{
return *addr;
}这里要注意几点：
- 加static：防止多个源文件包含时产生重复定义
- 加inline：提示编译器尝试内联展开
- 函数体要小：内联函数如果太大，编译器可能忽略你的inline请求
嗯，这里要注意——内联不是免费的。每个调用点都会复制一份函数体，代码体积会膨胀。我在一个资源紧张的MCU项目里，就因为滥用内联，导致flash空间不够用。后来改成普通函数，省了将近2KB。
宏定义规范——别让宏变成坑
宏是C语言的老祖宗留下的遗产，用好了是利器，用不好是灾难。我总结了几条铁律：
- 宏名全大写：
#define BUFFER_SIZE 256，一眼就能跟变量区分 - 带参数的宏要加括号：
/* 错误写法 */
#define SQUARE(x) x * x
/* 调用 SQUARE(1+2) 展开成 1+2*1+2 = 5，不是9 */
/* 正确写法 */
#define SQUARE(x) ((x) * (x))你看，少两个括号，结果就完全不对了。我当年刚入行时就犯过这个错，查了半天才发现是宏定义的问题。
- 多行宏用do-while包裹：
#define LOG_ERROR(msg) do { \
printf("Error: %s\n", msg); \
error_count++; \
} while(0)这样写的好处是，宏在if-else语句里使用时不会出问题。你想想看，如果不加do-while，if (cond) LOG_ERROR("fail"); else ... 展开后可能就语法错误了。
我的建议：能用内联函数就别用带参数的宏。内联函数有类型检查，宏没有。宏只是文本替换，编译器不会帮你检查参数类型对不对。
头文件包含的黄金法则
最后分享一个我一直在用的原则：
| 场景 | 做法 |
|---|---|
| 头文件里只用到了指针 | 前向声明即可，不需要包含头文件 |
| 头文件里用到了结构体定义 | 必须包含定义该结构体的头文件 |
| 头文件里用到了宏或枚举 | 必须包含定义该宏或枚举的头文件 |
说白了就是：能不包含就不包含，能前向声明就别include。这样可以减少编译依赖，加快编译速度。我在一个大型项目里，光优化头文件包含关系，就把全量编译时间从40分钟降到了25分钟。
避坑指南：我曾经在一个项目里，A.h包含了B.h，B.h又包含了A.h，形成了循环包含。虽然头文件卫士能防止无限递归，但编译顺序稍微一变，就出现「未定义类型」的错误。解决办法是拆出公共类型定义到单独的头文件里。
头文件规范就这些。记住：头文件是模块的接口，写得好不好直接影响到整个项目的可维护性。别图一时省事，后面改bug改到哭。