C语言头文件/工程组织原则

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

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

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

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

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

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

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

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

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

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

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

二、 头文件包含原则
在实际编程中，常常因头文件包含不当而引发编译时报告符号未定义的错误或重复定义的警告。要消除符号未定义的编译错误，只需在引用符号(变量、函数、数据类型及宏等)前确保它已被声明或定义[4]。要消除重复定义的警告，则需合理设计头文件包含顺序和层次。

 建议包含头文件时遵循以下原则：

 1）源文件内的头文件包含顺序应从最特殊到一般，如：

#include “通用头文件” //内部可能定义本模块数据类型别名

#include “源文件同名头文件”

#include “本模块其他头文件”

#include “自定义工具头文件”

#include “第三方头文件”

#include “平台相关头文件”

#include “C++库头文件”

#include “C库头文件”

 优点是每个头文件必须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，如此可减少依赖性方面的问题。

9）避免包含重量级的平台头文件，如windows.h或d3d9.h等。若仅使用该头文件少量函数，可extern函数到源文件内。
10）对于函数库(包括标准库和自定义的公共宏及接口)的头文件，可将其加入到一个通用头文件中。需要控制该头文件的体积(主要是该头文件所包含的所有头文件内容大小)，并确保所有源文件首先包含该通用头文件。
11）若不确定类型、宏定义或函数声明所在头文件具体路径，可在源文件中再次定义或声明，编译器会以redefined警告或conflicting错误给出类型、宏定义或函数声明所在头文件路径。

三、 代码文件组织原则
建议C语言项目中代码文件组织遵循以下原则：

 1）使用层次化和模块化的软件开发模型。每个模块只能使用所在层和下一层模块提供的接口。

 2）每个模块的文件(可能多个)保存在一个独立文件夹中。

 模块文件较多时可采用子目录的方式，物理上隔离不同层次的文件。子目录下源文件和头文件应分开存放，如分别置入include和source目录。

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

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

 5）按相同功能或相关性组织源文件和头文件。同一文件内的聚合度要高，不同文件中的耦合度要低。

 在对既有工程做单元测试时，耦合度低的文件布局非常便于搭建环境。

 6）声明和定义分开，使用头文件暴露模块需要提供给外部的类型、宏、变量和函数。尽量做到模块对外部透明，用户在使用模块功能时无需了解具体的实现。

 7）作为对外接口的头文件一经发布，应保持稳定。修改时一定要慎重。 

 8）文件夹和文件命名要能够反映出模块的功能。 

 9）正式版本和测试版本使用统一文件，使用宏控制是否产生测试输出。

 10）必要的注释不可缺少。   

四、全局变量使用原则
1）若全局变量仅在单个源文件中访问，则可将该变量改为该文件内的静态全局变量；

2）若全局变量仅由单个函数访问，则可将该变量改为该函数内的静态局部变量；

3）尽量不要使用extern声明全局变量，最好提供函数访问这些变量。直接暴露全局变量是不安全的，外部用户未必完全理解这些变量的含义。

4）设计和调用访问动态全局变量、静态全局变量、静态局部变量的函数时，需要考虑重入问题。

转载自：https://www.cnblogs.com/clover-toeic/p/3728026.html