4、头文件规范：包含卫士、头文件依赖、接口声明与内部实现分离
头文件这东西，看着简单，但坑特别多。我见过太多项目因为头文件乱成一锅粥，编译报错几百条，查半天发现是循环包含。说白了，头文件规范就是给代码立规矩，让模块之间清清楚楚、干干净净。
4.1 包含卫士：别让同一个头文件被包含两次
先问个问题：为什么需要包含卫士？
C语言预处理器处理 #include 时，就是简单的文本替换。如果头文件A包含了头文件B，而源文件又同时包含了A和B，那B的内容就被展开了两次。结构体重复定义、宏重复定义，编译器直接报错。
解决方案有两种：
| 方式 | 写法 | 说明 |
|---|---|---|
#ifndef 宏 |
|
传统方式，兼容所有编译器 |
#pragma once |
|
现代方式，简洁但非标准 |
我个人习惯用 #ifndef 方式。为什么？因为它是C标准的一部分，移植性最好。我在一个项目里用过 #pragma once，结果换到某款老旧的ARM编译器上就不认了，折腾了半天才找到原因。
命名规范建议：宏名用全大写，格式为 __模块名_H__。比如 __UART_DRIVER_H__、__TIMER_H__。注意前后各有两个下划线，这是嵌入式行业的常见做法。
4.2 头文件依赖：能少则少，能浅则浅
头文件依赖，说白了就是你的头文件里 #include 了多少东西。依赖越多，编译越慢，而且容易引发连锁问题。
我遇到过最夸张的一个项目，一个头文件里 #include 了二十多个其他头文件。改一个底层驱动，结果上层十几个模块都要重新编译。你说这效率能高吗？
怎么控制依赖？记住三条原则：
- 能不包含就不包含：如果只需要指针类型，用前置声明代替
#include - 能不暴露就不暴露：内部使用的头文件，别在公共头文件里包含
- 能分层就分层：依赖关系应该是单向的，别搞成循环依赖
举个例子：
// 不好的做法：uart.h 里包含了 timer.h
#include "timer.h"
typedef struct {
uint32_t baud;
TimerHandle_t timeout; // 其实只需要指针
} UartConfig_t;
// 好的做法：用前置声明
typedef struct Timer Timer_t; // 前置声明
typedef struct {
uint32_t baud;
Timer_t *timeout; // 指针类型，不需要完整定义
} UartConfig_t;我曾经踩过一个坑：在头文件里包含了某个驱动模块，结果那个驱动模块又反向包含了我的头文件，形成了循环依赖。编译报错信息完全看不懂，查了整整一天。从那以后，我要求团队必须用工具检查头文件依赖关系，发现循环依赖立即整改。
4.3 接口声明与内部实现分离
这是头文件规范里最重要的一条。说白了就是：头文件只放别人需要的东西，内部实现细节藏起来。
具体怎么做？
- 公共头文件（如
module.h）：放外部模块需要调用的函数声明、数据结构定义、宏定义 - 私有头文件（如
module_private.h）：放内部函数、内部结构体、内部宏 - 实现文件（如
module.c）：放函数实现，只包含必要的头文件
看个实际例子：
// uart.h - 公共头文件
#ifndef __UART_H__
#define __UART_H__
#include <stdint.h>
/* 对外接口 */
void UART_Init(uint32_t baud);
void UART_SendByte(uint8_t data);
uint8_t UART_ReceiveByte(void);
#endif /* __UART_H__ */
// uart_private.h - 私有头文件
#ifndef __UART_PRIVATE_H__
#define __UART_PRIVATE_H__
#include "uart.h"
/* 内部数据结构 - 外部不需要知道 */
typedef struct {
uint32_t baud;
uint8_t tx_buffer[256];
uint8_t rx_buffer[256];
volatile uint16_t tx_head;
volatile uint16_t tx_tail;
} UartContext_t;
/* 内部函数 - 外部不需要调用 */
void UART_ISR_Handler(void);
void UART_DMA_Config(void);
#endif /* __UART_PRIVATE_H__ */你想想看：如果外部模块能看到内部结构体，那别人就可能直接访问你的内部变量。哪天你改了内部实现，所有依赖这个结构体的模块都得跟着改。这不是给自己找麻烦吗？
分离的好处很明显：
- 降低耦合：外部模块只依赖公共接口，内部随便改
- 提高可读性：看公共头文件就知道这个模块能干什么
- 方便测试：测试代码可以包含私有头文件，直接访问内部状态
一个小技巧：在私有头文件里加个注释标记，比如 /* INTERNAL - DO NOT INCLUDE DIRECTLY */。这样别人一看就知道这不是公共接口。我在团队里还加了个编译检查，如果公共模块包含了私有头文件，直接报错。
4.4 总结一下
头文件规范其实就三件事：
- 包含卫士：每个头文件都必须有，防止重复包含
- 控制依赖：能不包含就不包含，能用前置声明就用前置声明
- 分离接口与实现：公共头文件只放接口，内部细节藏到私有头文件里
嗯，这些规则看着简单，但真正坚持做下来不容易。我见过太多项目，一开始挺规范，后来赶进度就开始乱来了。结果呢？后期维护成本翻倍，改个bug都得小心翼翼。所以，从一开始就把规矩立好，后面会省很多事。