C语言头文件组织与包含原则

说明

本文假定读者已具备基本的C编译知识。

如非特殊说明，文中“源文件”指*.c文件，“头文件”指*.h文件，“引用”指包含头文件。

一、头文件作用

C语言里，每个源文件是一个模块，头文件为使用该模块的用户提供接口。接口指一个功能模块暴露给其他模块用以访问具体功能的方法。使用源文件实现模块的功能，使用头文件暴露单元的接口。用户只需包含相应的头文件就可使用该头文件中暴露的接口。

通过头文件包含的方法将程序中的各功能模块联系起来有利于模块化程序设计:

1）通过头文件调用库功能。在很多场合，源代码不便(或不准)向用户公布，只要向用户提供头文件和二进制库即可。用户只需按照头文件中的接口声明来调用库功能，而不必关心接口如何实现。编译器会从库中提取相应的代码。

2）头文件能加强类型安全检查。若某个接口的实现或使用方式与头文件中的声明不一致，编译器就会指出错误。这一简单的规则能大大减轻程序员调试、改错的负担。

在预处理阶段，编译器将源文件包含的头文件内容复制到包含语句(#include)处。在源文件编译时，连同被包含进来的头文件内容一起编译，生成目标文件(.obj)。如果所包含的头文件非常庞大，则会严重降低编译速度(使用GCC的-E选项可获得并查看最终预处理完的文件)。因此，在源文件中应仅包含必需的头文件，且尽量不要在头文件中包含其它头文件。

二、 头文件组织原则

源文件中实现变量、函数的定义，并指定链接范围。头文件中书写外部需要使用的全局变量、函数声明及数据类型和宏的定义。

建议组织头文件内容时遵循以下原则：

1）头文件划分原则：类型定义、宏定义尽量与函数声明相分离，分别位于不同的头文件中。内部函数声明头文件与外部函数声明头文件相分离，内部类型定义头文件与外部类型定义头文件相分离。

注意，类型和宏定义有时无法分拆为不同文件，比如结构体内数组成员的元素个数用常量宏表示时。因此仅分离类型宏定义与函数声明，且分别置于*.th和*.fh文件(并非强制要求)。

2）头文件的语义层次化原则：头文件需要有语义层次。不同语义层次的类型定义不要放在一个头文件中，不同层次的函数声明不要放在一个头文件中。

3）头文件的语义相关性原则：同一头文件中出现的类型定义、函数声明应该是语义相关的、有内部逻辑关系的，避免将无关的定义和声明放在一个头文件中。

4）头文件名应尽量与实现功能的源文件相同，即module.c和module.h。但源文件不一定要包含其同名的头文件。

5）头文件中不应包含本地数据，以降低模块间耦合度。

即只有源文件自己使用的类型、宏定义和变量、函数声明，不应出现在头文件里。作用域限于单文件的私有变量和函数应声明为static，以防止外部调用。将私有类型置于源文件中，会提高聚合度，并减少不必要的格式外漏。

6）头文件内不允许定义变量和函数，只能有宏、类型(typedef/struct/union/enum等)及变量和函数的声明。特殊情况下可extern基本类型的全局变量，源文件通过包含该头文件访问全局变量。但头文件内不应extern自定义类型(如结构体)的全局变量，否则将迫使本不需要访问该变量的源文件包含自定义类型所在头文件[1]。

7）说明性头文件不需要有对应的源文件。此类头文件内大多包含大量概念性宏定义或枚举类型定义，不包含任何其他类型定义和变量或函数声明。此类头文件也不应包含任何其他头文件。

8）使用#pragma once或header guard(亦称include guard或macro guard)避免头文件重复包含。#pragma once是一种非标准但已被现代编译器广泛支持的技巧，它明确告知预处理器“不要重复包含当前头文件”。而header guard则通过预处理命令模拟类似行为：

typedef struct DefStruct_t DefStruct;
typedef BOOL (*func)(const DefStruct *ptStrt);

struct DefStruct_t{
int i;
func f;
};

Correct Code
注意，在前向声明和具体定义之间涉及标识符(变量、结构、函数等)实现细节的使用都是非法的。若函数被前向声明但未被调用，则编译和运行正常；若前向声明函数被调用但未被定义，则编译正常但链接报错(undefined reference)。将具体定义放在源文件中可部分避免该问题。