6、源文件与头文件的配对：.c 文件与 .h 文件的职责划分、如何组织一对文件
好，咱们今天聊点实在的。.c 和 .h 怎么配对，这事儿看着简单，但我在代码评审里见过太多翻车的例子。说白了，就是职责没划清楚。
你想想看，一个模块就是一个 .c 配一个 .h。这俩文件就像一对搭档，各有各的活。搞混了，代码就乱成一锅粥。
6.1 职责划分：谁该干什么
我个人的习惯是这么分的——.c 文件负责干活，.h 文件负责告诉别人怎么调用。就这么简单。
| 文件 | 核心职责 | 放什么 | 不放什么 |
|---|---|---|---|
| .c 文件 | 实现细节 | 函数定义、全局变量定义、内部静态函数、内部宏 | 外部接口声明、类型定义（除非模块内部用） |
| .h 文件 | 接口声明 | 函数声明、extern 变量声明、结构体/枚举定义、对外宏 | 函数实现、变量定义、内部实现细节 |
举个例子，你写一个 LED 驱动模块：
// led_driver.h
#ifndef LED_DRIVER_H
#define LED_DRIVER_H
#include <stdint.h>
typedef enum {
LED_OFF = 0,
LED_ON,
LED_BLINK
} led_state_t;
void led_init(void);
void led_set_state(led_state_t state);
#endif
// led_driver.c
#include "led_driver.h"
#include <avr/io.h> // 硬件相关头文件
static uint8_t current_state = LED_OFF;
void led_init(void) {
DDRB |= (1 << 5); // 设置 PB5 为输出
PORTB &= ~(1 << 5); // 初始关闭
}
void led_set_state(led_state_t state) {
current_state = state;
switch(state) {
case LED_ON:
PORTB |= (1 << 5);
break;
case LED_OFF:
PORTB &= ~(1 << 5);
break;
case LED_BLINK:
// 闪烁逻辑...
break;
}
}
看到了吗？.h 只暴露了接口，.c 藏起了硬件操作和内部状态。这就是封装。
核心原则：.h 是合同，.c 是履约。合同上写什么，外面就用什么。合同没写的，外面别碰。
6.2 组织一对文件：我的实战套路
我在项目里带团队时，要求每个模块的文件必须按这个模板来组织。嗯，踩过坑之后总结出来的。
6.2.1 .h 文件的组织顺序
- 头文件保护宏：
#ifndef XXX_H/#define XXX_H/#endif - 包含的头文件：只包含接口依赖的，不要乱引
- 类型定义：结构体、枚举、typedef
- 宏定义：对外公开的宏
- 全局变量声明：用
extern修饰 - 函数声明：按功能分组，加注释说明
6.2.2 .c 文件的组织顺序
- 包含自己的 .h：第一行就写
#include "xxx.h" - 包含其他需要的头文件：系统头文件、其他模块头文件
- 内部宏定义：模块内部用的宏，比如缓冲区大小
- 内部类型定义：外部不需要知道的结构体
- 静态全局变量：加
static限制作用域 - 内部函数：加
static，外部不可见 - 接口函数实现：与 .h 中的声明一一对应
一个小技巧：.c 文件第一行就包含自己的 .h，这样编译时能检查 .h 中的声明和 .c 中的定义是否一致。我曾经因为这个习惯，避免了好几次接口不匹配的 bug。
6.3 常见翻车现场
说几个我亲眼见过的坑，你注意避一避。
坑一：在 .h 里写函数实现
有人图省事，把短函数直接写在 .h 里。结果多个 .c 文件包含这个 .h，链接时报重复定义。除非你加
有人图省事，把短函数直接写在 .h 里。结果多个 .c 文件包含这个 .h，链接时报重复定义。除非你加
static inline，否则别这么干。
坑二：在 .h 里定义变量
int flag; 写在 .h 里，每个包含它的 .c 都会定义一份。链接时直接报错。记住，.h 里只能 extern int flag;，定义放 .c。
坑三：循环包含
a.h 包含 b.h，b.h 又包含 a.h。编译直接卡死。解决方案：能用前置声明就别包含头文件。
a.h 包含 b.h，b.h 又包含 a.h。编译直接卡死。解决方案：能用前置声明就别包含头文件。
6.4 知识体系：一张图说清楚
下面这张图，是我给团队培训时画的。它把 .c 和 .h 的关系、职责、以及编译链接的流程串起来了。
6.5 避坑指南：我踩过的雷
我曾经在一个项目里，接手了一个遗留代码。那个模块的 .h 文件里居然有 200 行的函数实现。你猜怎么着？每次改一个 bug，要重新编译十几个文件。后来我花了两天时间重构，把实现全挪回 .c，编译时间从 3 分钟降到了 20 秒。
还有一次，团队里有人把全局变量定义在了 .h 里。结果链接的时候报了一堆重复定义。查了半天才发现，是三个 .c 文件都包含了同一个 .h。从那以后，我要求所有 .h 里的变量声明必须加 extern，并且用注释标出定义在哪个 .c 里。
我的个人习惯：每个 .h 文件开头加一段注释，写明这个模块的职责、依赖哪些模块、以及注意事项。比如：
// led_driver.h - LED 驱动模块，依赖 gpio.h，注意初始化前调用 led_init()
说白了，.c 和 .h 的配对，核心就是接口与实现分离。你把这个原则吃透了，代码自然就清晰了。别小看这个，很多大型项目代码乱，根子就在这。