介绍
任何使用 c 或 c++ 编程的人都知道，组成 api 的常量、宏、类型、结构（或类）和函数声明被放入 头文件 通常具有 .h （或有时为 c++ 的 .hpp）文件扩展名。
然而，许多解释都忽略了头文件中的代码应该如何组织，包括包含其他头文件的顺序。这对于帮助最大限度地提高编译速度和整体可维护性很重要。
c++20 添加了模块，但那是另一个故事了。 鉴于存在大量 c 和 c++20 之前的代码，头文件将继续存在一段时间。
包括警卫
基本的头文件如下：
// foo.h #ifndef foo_h #define foo_h // ... declarations ... #endif /* foo_h */
也就是说，所有声明都应该位于 include guard 中： #ifndef x, #define x, #endif /* x */ 序列，其中 x 是代码库中的唯一名称并派生从文件名。
包含防护的要点是，如果多次包含特定头文件，则编译器不会收到多个声明错误，因为预处理器将忽略防护中已定义的所有内容。
包含保护名称的命名法并不重要：只需选择一种不太可能与系统或第三方标头中使用的名称发生冲突的方法 - 并且保持一致。
#endif 之后的注释当然不是必需的，但为了可读性，最好总是重复 #ifndef（或 #ifdef 或 #if）中使用的条件。
然后在所有使用该标头的 .c（或 .cpp）文件中，只需 #include 它：
// foo.c #include "foo.h" // ... definitions ...
不幸的是，这通常是许多头文件解释停止的地方。有效地创建和使用头文件远不止这些。
自给自足的标头
在继续之前，我想定义头文件自给自足：
意味着什么- 自给自足的标头 是指如果将其自身包含到 .c（或 .cpp）文件中，则该文件将在编译时不会出现错误（具体来说，不会出现“未声明”错误）。
例如，一个简单的程序，例如：
#include "foo.h"
int main() {
}
只有当 foo.h 是自给自足的时候，编译才会没有错误。
在标头中包含其他标头
通常，头文件需要包含其他头文件，因为声明使用了其他头文件中的其他声明。
在头文件中：
- 首先包含其他本地标头（如果有），然后是系统标头（如果有）。
例如：
// color.h #ifndef cdecl_color_h #define cdecl_color_h #include "config.h" // correct: #include local headers ... #include "strbuf.h" #include "util.h" #include <stdio.h> // ... before system headers. // ... #endif /* cdecl_color_h */
本地标头（用“”括起来的）（如果有的话）放在前面，然后是系统标头（用 <> 括起来的）（如果有的话）。
为什么？因为这有助于确保每个头文件都是自给自足的。 例如，如果您将系统标头放在前面：
#include <stdio.h> // wrong: #include of system headers ... #include "strbuf.h" // ... before local headers. // ...
那么 strbuf.h 中的声明就可以“意外”使用 stdio.h 中的声明（例如 file），而无需 strbuf.h 本身包括 stdio.h。
这将无限期地继续工作，但如果在某个时候您不再需要 color.h 中的 stdio.h 并因此删除 #include <stdio.h>，那么您将在 strbuf.h 中收到“未声明”错误。 直到此时，您永远不会注意到 strbuf.h 不是自给自足的。
一旦您注意到，它很容易修复，但最好首先通过始终在系统标头之前包含本地标头来避免该问题。
前向声明而不是包含
在 c 头文件中：
- 如果您仅通过指针使用在另一个标头中声明的结构或联合类型，请前向声明该类型而不是包含其他标头。
例如，如果您的标头 print.h 使用标准标头 pwd.h 中声明的 passwd 结构，但仅通过指针（并且您不需要 pwd.h 中的任何其他内容），则前向声明 passwd 而不是包含 pwd。小时：
// print.h struct passwd; // instead of: #include <pwd.h> void print_passwd( struct passwd *pw );
为什么？ 当您只需要一个声明时，它节省了预处理器必须打开 pwd.h 的时间以及编译器必须解析整个文件的时间。 对于大型 c 或 c++ 代码库，时间会增加。
c++ 的等效指南类似，但包括类和引用：
- 如果您仅通过指针或引用使用在另一个标头中声明的结构、联合或类类型，请前向声明该类型，而不是包含其他标头。
包括一切必要的东西
在头文件中：
- 您必须包含它需要自给自足的所有其他标头（或前向声明）。
永远不要强迫您的标头的用户必须在您的标头之前包含一些其他标头，以便编译时不会出现错误。
bsd 派生的操作系统历来倾向于违反此准则。 这样做的理由是，这是帮助最大化编译速度的另一种方法。 它通过强迫你成为人类包括守卫来做到这一点。
例如：
#include <sys/types.h> #include <pwd.h> // needs <sys/types.h> #include <unistd.h> // needs <sys/types.h> too
pwd.h 和 unistd.h 各自执行#include <sys/types.h>，而是依赖您自己执行包含操作。
这有什么帮助？ 它消除了预处理器必须打开 sys/types.h、读取文件、遇到包含防护并忽略其余内容（如果之前已见过该防护）的步骤（如 unistd.h 的情况） .
因此，虽然它确实有帮助，但代价是它迫使用户必须记住手动包含文件，这可能会导致不必要的包含，从而减慢编译速度。 例如，如果在某个时候您删除了 pwd.h 和 unistd.h 的包含内容，则可能会导致不再需要 sys/types.h，但您可能会忘记删除它。
与计算机科学中的许多其他事物一样，这是一种权衡。 bsd 派生的操作系统已经放弃了这种做法，并使标头自给自足。
子目录
大型代码库通常将代码划分到子目录中，每个子目录包含一组相关文件。 对于 #include "..."，预处理器仅在当前目录中查找，不在其子目录中查找。
要在子目录中使用标头，有两种选择：
- 使用引号之间的子目录名称；或：
- 告诉编译器也查看子目录。
第一个示例是：
#include "subsystem/out_q.h"
执行第二个操作是特定于编译器的，但对于基于 unix 的编译器（例如 gcc 和 clang），您通常会添加 -isubsystem 形式的命令行选项，将子系统添加到编译器包含路径.
这两种方法都可以，但如果您采用第二种方法，头文件名必须在整个代码库中是唯一的。 如果不同子目录中的两个标头具有相同的名称，则包含其中一个标头将仅包含编译器包含路径中较早的标头。
仅大小写差异
另一件事不要做的是：
- 不要有名称不同的文件仅大小写不同。
例如，不有out_q.h 和 out_q.h。为什么不呢？
- 很容易写错。
- 在不区分大小写但保留大小写的文件系统（例如 apfs 和 hfs+）上，此类文件被视为相同文件。
对于第二个问题，这可能意味着即使您包含 out_q.h，如果 out_q.h 在包含路径中排在第一位，您最终也可能会包含 out_q.h。
切勿使用../
你必须永远不要做的一件事是：
- 切勿在包含路径中使用 ../，例如：
#include "../subsystem/out_q.h"
为什么不呢？
代码库的构建过程可能使用符号链接，并且..可能最终相对于解析路径，而不是原始路径，因此您结束的目录up 包括 from 可能不是您想象的那样。 这可能会导致难以诊断的错误。
如果您的代码库架构良好，代码不应该具有循环依赖关系 - 并且包含路径将被适当设置以防止这种情况。
对于第二个，如果您尝试包含subsystem/out_q.h 并得到“没有这样的文件”，则意味着您不应该包含您的文件中的该文件正在努力，因为这会产生循环依赖。 使用 ../ 只是为了让你的代码编译破坏了这个有意的限制。
循环依赖通常很糟糕，因为它们可能会导致静态初始化顺序惨败。
在 .c 或 .cpp 文件中包含标头
对于 .c（或 .cpp）文件，在头文件中包含标头的所有准则也适用，但需要进行一项调整以包含本地标头：
- 对于给定的 .c（或 .cpp）文件，例如 foo.c，首先包含其相应的标头 foo.h。
为什么？这确保了 foo.h 是自给自足的。
结论
正确的头文件规范有助于最大限度地提高编译速度和整体可维护性。总结一下：
自给自足的标头 是一个如果将其自身包含到 .c（或 .cpp）文件中，则该文件将编译而不会出现错误（具体来说，没有“未声明”）错误）。
在头文件中，使用包含防护。
在头文件中，首先包含其他本地标头（如果有），然后包含系统标头（如果有）。
如果您使用仅通过指针（或 c++ 中的引用）在另一个标头中声明的结构或联合（或 c++ 中的类）类型，请前向声明该类型，而不是包含其他标头。
对于标头，您必须包含它需要自给自足的所有其他标头（或前向声明）。
不要有名称不同的文件仅大小写不同。
切勿在包含路径中使用 ../。
对于给定的 .c（或 .cpp）文件，例如 foo.c，首先包含其相应的标头 foo.h。
负责任地包含。
