青鸟激越 头文献组织与包含原则！纯干货

本文假设读者已具备基本的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则通过预措置敕令模拟同样行径：

使用#pragma once比拟header guard具有两个优点：

① 更快。编译器不会第二次读取标记#pragma once的文献，但却会读几许遍使用header guard 的文献(寻找#endif)；

② 更肤浅。不再需要为每个文献的header guard取名，幸免宏名重名激发的“找不到声明”问题。

流毒则是：

#pragma once保证物理上的并吞个文献不会被包含屡次，无法敌人文献中的一段代码作#pragma once声明。若某个头文献具有多份拷贝(内容交流的多个文献)，pragma不成保证它们不被重叠包含。虽然，这种重叠包含很容易被发现并修正。

9）C++中要援用C函数时，函数地方头文献内应包含extern "C"。

被extern "C"修饰的变量和函数将按照C言语神志编译和纠合，不然编译器将无法找到C函数界说，从而导致联络失败。

10）头文献内要有面向用户的富有扫视，从期骗角度形色接口深刻的内容。

三、 头文献包含原则

在本色编程中，继续因头文献包含不妥而激发编译时通告标记未界说的伪善或重叠界说的领导。

要放手标记未界说的编译伪善，只需在援用标记(变量、函数、数据类型及宏等)前确保它已被声明或界说[4]。要放手重叠界说的领导，则需合理筹划头文献包含模范和头绪。

建议包含头文献时解雇以下原则：

1）源文献内的头文献包含模范应从最特殊到一般，

如：

优点是每个头文献必须include需要的关联头文献，不然会报错。

同期，源文献同名头文献置于包含列表前端便于查验该头文献是否自完备，以及类型或函数声明是否与模范库突破。

2）减少头文献的嵌套和交叉援用，头文献仅包含其信得过需要显式包含的头文献。

举例，头文献A中出现的类型界说在头文献B中，则头文献A应包含头文献B，除此除外的其他头文献不允许包含。

头文献的嵌套和交叉援用会使法子组织结构和文献组织变得交集，同期形成潜在的伪善。大型工程中，原有头文献可能会被多个其他(源或头)文献包含，在原有头文献中添加新的头文献时时牵一发而动全身。若头文献中类型界说需要其他头文献时，可将其提议来单独形成一个全局头文献。

3）头文献应包含哪些头文献仅取决于本人，而非包含该头文献的源文献。

举例，编译源文献时需要用到头文献B，且源文献已包含头文献A，而索性将头文献B包含在头文献A中，这是伪善的作念法。

4）尽量保证用户使用此头文献时，无需手动包含其他前提头文献，即此头文献内已包含前提头文献。

举例，面积关系操作的头文献Area.h内已包含对于点操作的头文献Point.h，则用户包含Area.h后无需再手动包含Point.h。这么用户就不消了解头文献的内在依赖关系。

5）头文献应是自完备的，即在职一源文献中包含任一头文献而不会产生编译伪善。

6）源文献中包含的头文献尽量不要有模范依赖。

7）尽量在源文献中包含头文献，而非在头文献中。且源文献仅包含所需的头文献。

8）头文献中若能前置声明(亦称前向声明[5])，就不要包含另一头文献。仅现时置声明不成知足或过于缺乏时才使用include，如斯可减少依赖性方面的问题。

示举例下：

如上，在OmciChkFunc函数的收尾源文献内包含T_MeInfoMap和T_OmciMsg地方头文献即可。

另举一举例下：

如上，CompareRecFunc函数原型由其他头文献提供，此处为幸免头文献交叉援用界说其异名同构原型CmpRecFunc。

在不会引起歧义的前提下，头文献内尽可能使用VOID指针代替非基本类型的值变量或指针，以幸免再包含类型界说地方的头文献。但这将影响代码可读性并缩小法子实际效果，应比权量力。

9）幸免包含分量级的平台头文献，如windows.h或d3d9.h等。若仅使用该头文献少许函数，可extern函数到源文献内。如下：

若还使用该头文献某些类型和宏界说，可创建适配性源文献。在该源文献内包含平台头文献，封装新的接口并将其声明在同名头文献内，其他源文献将通过适鸳侣文献曲折访谒平台接口。如下：

10）对于函数库(包括模范库和自界说的大家宏及接口)的头文献，可将其加入到一个通用头文献中。需要适度该头文献的体积(主淌若该头文献所包含的系数头文献内容大小)，并确保系数源文献率先包含该通用头文献。示举例下：

瞩目，示例头文献内包含C库文献虽能简化包含，但却与规定1突破。也可另外增多包含库文献列表的通用头文献。

11）若概略情类型、宏界说或函数声明地方头文献具体旅途，可在源文献中再次界说或声明，编译器会以redefined领导或conflicting伪善给出类型、宏界说或函数声明地方头文献旅途。

四、代码文献组织原则

建议C言语神志中代码文献组织解雇以下原则：

1）使用头绪化和模块化的软件成立模子。每个模块只可使用地方层和下一层模块提供的接口。

2）每个模块的文献(可能多个)保存在一个零丁文献夹中。

模块文献较多时可秉承子目次的神志，物理上远离不同头绪的文献。子目次下源文献和头文献应分开存放，如分别置入include和source目次。

3）用于模块裁减的条款编译宏保存在一个零丁文献中，便于软件裁减。

4）硬件关系代码和操作系统关系代码与工程代码相对零丁保存，以便于软件移植。

5）按交流功能或关系性组织源文献和头文献。并吞文献内的团聚度要高，不同文献中的耦合度要低。

在对既有工程作念单位测试时，耦合度低的文献布局极端便于搭建环境。

6）声明和界说分开，使用头文献深刻模块需要提供给外部的类型、宏、变量和函数。尽量作念到模块对外部透明，用户在使用模块功能时无需了解具体的收尾。

7）当作对外接口的头文献依然发布，应保握相识。修改时一定要负责。

8）文献夹和文献定名要能够反馈出模块的功能。

9）郑再版块和测试版块使用斡旋文献，使用宏适度是否产生测试输出。

10）必要的扫视不可枯竭。