第二讲：头文件设计原则——模块的“公共接口”该怎么写？
大家好，我是你们的老朋友。今天咱们聊聊头文件。
说实话，我见过太多项目，代码写得挺漂亮，结果一看头文件——乱七八糟。有的把函数实现塞进去，有的连全局变量定义都往里扔，还有的连个重复包含保护都没有。嗯，这种项目，后期维护起来，那叫一个酸爽。
头文件是什么？说白了，它就是模块的“公共接口”。就像你家的门牌号，别人想找你，得先知道门牌号。头文件就是告诉别人：“嘿，我这里有什么函数、什么类型、什么宏，你可以用。”
但注意，它只是“告诉”，不是“给”。你家的门牌号不会把整个房子搬过去，对吧？
一、头文件的核心作用
头文件的作用，我总结为三点：
- 声明接口：告诉其他模块，我这个模块提供了哪些函数、类型、宏。
- 共享常量与宏：比如错误码、配置参数，大家统一用一套定义。
- 类型定义：结构体、枚举、联合体，这些类型需要在多个源文件中使用。
我记得有一次，接手一个老项目，头文件里居然写了函数实现。编译倒是能过，但链接的时候各种重复定义。我花了整整两天才把那些“野实现”清理干净。从那以后，我对头文件的“边界感”特别敏感。
二、防止重复包含：老生常谈但必须谈
你想想看，如果两个头文件互相包含，或者一个头文件被多次包含，会发生什么？
编译器会报“重复定义”的错误。更麻烦的是，如果头文件里有类型定义，重复包含会导致类型重定义，编译直接挂掉。
解决方案？就是那个经典的“三件套”：
#ifndef __MY_MODULE_H__
#define __MY_MODULE_H__
/* 头文件内容写在这里 */
#endif /* __MY_MODULE_H__ */这个写法，我习惯叫它“头文件守卫”。第一次包含时，__MY_MODULE_H__ 没定义，所以进入条件编译，定义这个宏，然后处理内容。第二次再包含时，宏已经定义了，直接跳过整个内容。
uart_driver.h，就用 __UART_DRIVER_H__。这样一看就知道是哪个文件，不会搞混。
另外，#pragma once 也能达到同样效果。但我个人更推荐 #ifndef 方案，因为它是标准 C 的写法，移植性更好。有些老编译器不认识 #pragma once，你想想看，万一项目要移植到某个嵌入式平台，编译器不支持，那就尴尬了。
三、头文件里应该放什么？
这个问题，我直接给清单：
| 可以放的内容 | 说明 |
|---|---|
| 函数声明（原型） | 比如 int uart_init(int baudrate); |
| 类型定义 | typedef struct { ... } UartConfig; |
| 宏定义 | #define UART_BAUD_115200 115200 |
| 外部变量声明 | extern int uart_error_count;（注意是 extern） |
| 内联函数 | 短小的、性能敏感的，用 static inline 修饰 |
举个例子，一个典型的 UART 驱动头文件长这样：
#ifndef __UART_DRIVER_H__
#define __UART_DRIVER_H__
#include <stdint.h>
/* 波特率宏定义 */
#define UART_BAUD_9600 9600
#define UART_BAUD_115200 115200
/* 错误码 */
#define UART_OK 0
#define UART_ERR_INIT -1
#define UART_ERR_TIMEOUT -2
/* 配置结构体 */
typedef struct {
uint32_t baudrate;
uint8_t data_bits;
uint8_t stop_bits;
uint8_t parity;
} UartConfig;
/* 函数声明 */
int uart_init(const UartConfig *cfg);
void uart_send_byte(uint8_t data);
int uart_receive_byte(uint8_t *data, uint32_t timeout_ms);
/* 外部变量声明 */
extern int uart_initialized;
#endif /* __UART_DRIVER_H__ */你看，这个头文件只放“接口”相关的东西。具体怎么实现，那是 .c 文件的事。
四、头文件里不应该放什么？
这个更重要。我直接说“禁区”：
- 函数定义（实现）：除非是
static inline，否则别放。否则多个.c文件包含它，链接时就会报重复定义。 - 全局变量定义：比如
int uart_error_count;不带extern。这会在每个包含它的.c文件里都定义一个同名变量，链接时直接冲突。 - 静态函数或静态变量：这些是模块内部的东西，不应该暴露给外部。
- 实现细节：比如某个算法的内部数据结构、某个寄存器的直接操作宏。这些应该藏在
.c文件里。
int system_tick = 0;。结果三个源文件都包含了这个头文件，链接时报“multiple definition”。我查了半天，最后发现是头文件里多了个定义。从那以后，我养成了一个习惯：头文件里所有变量声明，前面必须加 extern，否则就是错的。
还有一个常见的误区：把 #include 放在头文件里，但又不加条件编译保护。这会导致头文件被多次包含时，里面的 #include 也被重复执行，增加编译时间。虽然不会报错，但效率低。我建议，头文件里只包含它真正需要的头文件，不要“顺手”包含一堆没用的。
五、知识体系总览
下面这张图，是我画的一个头文件设计原则的思维导图。你可以把它当作一个检查清单：
六、一些实战建议
最后，分享几个我个人的习惯：
- 头文件命名：和
.c文件同名。比如uart_driver.c对应uart_driver.h。这样找起来方便。 - 一个头文件对应一个模块：不要搞“万能头文件”，把所有东西都塞进去。那样虽然省事，但耦合度太高，改一处牵全身。
- 头文件里尽量少包含其他头文件：能用前置声明（
struct xxx;）就别用#include。这样可以减少编译依赖，加快编译速度。 - 写注释：每个函数声明前面，写清楚参数含义、返回值、注意事项。别偷懒，你省下的那几分钟，将来可能花几小时来猜这个函数是干嘛的。
嗯，关于头文件设计，今天就聊这么多。记住一句话：头文件是给别人看的，不是给自己用的。你设计得越干净，别人用起来就越舒服。