引言
最近正在疯狂补技术债，以及疯狂赶项目…大一大二摸的鱼终归是要还的，也奉劝大家少摸鱼，不然临近找工作可能就会像我一样焦虑。
在写C++项目中，碰到一个非常古怪的问题，当我像往常一样引入一个头文件时，vscode居然给我报红了（我在vscode中使用的是clangd插件）：
当时就觉得非常震惊，我从未没碰到过只是include一个头文件，居然会报错的情况，当我以为是插件的问题，像往常一样mkdir build && cd build && cmake .. && make时，gcc也给出了一大堆诸如‘xxx’ does not name a type; did you mean ‘xxx’?、‘xxx’ was not declared in this scope、class ‘xxx::xxx’ does not have any field named ‘xxx’这种显然是未定义才会有这种“简单”的报错。百度和Google给出的信息也很少。
经过思考和搜索，我发现这就是头文件递归包含的问题，在这个项目的一小个模块中，头文件的引用顺序如下：
可以看到，蓝色和红色的包含顺序成为了一个闭环，造成了头文件的递归包含，如果是两个头文件成环，那么也叫做头文件互相包含问题。
下面请大家跟着我来探讨这个问题的成因，以及解决方案。
初始版本
最基本的，我们肯定知道，C/C++语言是头文件和源文件分离的，这样能够有效的防止重复定义，也简化了编译依赖，并且我们也可以把我们的代码编译为动态库或者静态库供他人使用，一定程度上也是一种安全性的提升，著名的pimpl就是基于此实现的。
我们假设有一个工具类A，带有对应的.h和.cc文件，还有一个main.cc调用它，那么大概长下面这个样子：
- a.h
class A {
public:
void SomeMemberFunc();
};
- a.cc
#include "a.h"
void A::SomeMemberFunc() {
// Very long and not suitable for inline functions
}
- main.cc
#include "a.h"
int main(int argc, char *argv[]) {
A().SomeMemberFunc();
return 0;
}
编译成功：
➜ v1 git:(master) ✗ g++ main.cc a.cc
➜ v1 git:(master) ✗ ./a.out
头文件守卫
C/C+允许嵌套包含，但不允许递归包含。嵌套包含就是：a.h包含b.h，b.h包含c.h，等等。
方便起见，我加了一个b.h（其中包含了a.h），在初始版本的情况下，这样则会报错：
➜ v2 git:(master) ✗ g++ main.cc a.cc
In file included from b.h:1,
from main.cc:2:
a.h:1:7: error: redefinition of ‘class A’
1 | class A {
| ^
In file included from main.cc:1:
a.h:1:7: note: previous definition of ‘class A’
1 | class A {
| ^
➜ v2 git:(master) ✗
解决方案是#pragma once或者#ifndef #define #endif，相信大家都用过。区别是前者依赖于编译器，后者可移植性更好，但宏名我们需要自己控制，一般用后者更多。
加上它后，编译错误消失：
➜ v3 git:(master) ✗ g++ main.cc a.cc
➜ v3 git:(master) ✗
递归包含会怎么样
虽然说，项目如果出现了递归包含，可能代表代码逻辑错误，但是有的场景确实需要，也难以避免，我们来模拟一下这种场景。
我们有两个类的头文件，a.h代表class A，b.h代表class B，class A和class B中各有一个对方的实例，main.cc只是简单包含它们，并创建各自class的对象。
如下：
- a.h
#ifndef A_H_
#define A_H_
#include "b.h"
class A {
B b;
};
#endif // !A_H_
- b.h
#ifndef B_H_
#define B_H_
#include "a.h"
class B {
A a;
};
#endif // !B_H_
- main.cc
#include "a.h"
#include "b.h"
int main(int argc, char *argv[]) {
A();
B();
return 0;
}
注意上面两个头文件的头文件守卫都好着，但是编译却出错了：
➜ v4 git:(master) ✗ g++ main.cc
In file included from a.h:4,
from main.cc:1:
b.h:7:3: error: ‘A’ does not name a type
7 | A a;
| ^
为什么会出错
先说结论，正是因为头文件守卫的存在，导致class B在声明时，编译器并不知道class A是啥。
直接看预处理后的结果，具体怎么来的交给大家去想：
➜ v4 git:(master) g++ -E main.cc
# 1 "main.cc"
# 1 "<built-in>"
# 1 "<command-line>"
# 1 "/usr/include/stdc-predef.h" 1 3 4
# 1 "<command-line>" 2
# 1 "main.cc"
# 1 "a.h" 1
# 1 "b.h" 1
# 1 "a.h" 1
# 5 "b.h" 2
class B {
A a;
};
# 5 "a.h" 2
class A {
B b;
};
# 2 "main.cc" 2
int main(int argc, char *argv[]) {
A();
B();
return 0;
}
难怪我的项目一编译也是各种类型不存在的错误，这样一来问题就明了了。
前置声明是什么
引用Google C++风格指南中的一些话：
- 定义：所谓「前置声明」（forward declaration）是类、函数和模板的纯粹声明，没伴随着其定义.
- 优点：
- 前置声明能够节省编译时间，多余的 #include 会迫使编译器展开更多的文件，处理更多的输入。
- 前置声明能够节省不必要的重新编译的时间。 #include 使代码因为头文件中无关的改动而被重新编译多次。
- 缺点：
- 前置声明隐藏了依赖关系，头文件改动时，用户的代码会跳过必要的重新编译过程。
- 前置声明可能会被库的后续更改所破坏。前置声明函数或模板有时会妨碍头文件开发者变动其 API. 例如扩大形参类型，加个自带默认参数的模板形参等等。
- 前置声明来自命名空间 std:: 的 symbol 时，其行为未定义。
- 很难判断什么时候该用前置声明，什么时候该用 #include 。极端情况下，用前置声明代替 #include 甚至都会暗暗地改变代码的含义：
// b.h:
struct B {
};
struct D : B {
};
// good_user.cc:
#include "b.h"
void f(B*);
void f(void*);
void test(D* x) {
f(x); } // calls f(B*)
- 如果 #include 被 B 和 D 的前置声明替代， test() 就会调用 f(void*) .
- 前置声明了不少来自头文件的 symbol 时，就会比单单一行的 include 冗长。
- 仅仅为了能前置声明而重构代码（比如用指针成员代替对象成员）会使代码变得更慢更复杂.
- 结论：
- 尽量避免前置声明那些定义在其他项目中的实体.
- 函数：总是使用 #include.
- 类模板：优先使用 #include.
如何解决递归包含问题
经过上一小节的了解，我们了解到，前置声明是解决问题的答案。尽管人家Google建议我们不要使用，但毕竟这也是没有办法的办法，人也说了，类模板优先使用#include，但没说不能使用。
在我看来，最直接的缺点是，使用了前置声明，我们就只能在头文件中声明对象的指针或引用，这是不完全类型，所以我们也无法使用其成员，毕竟编译器实例化某个类型时，需要知道对象的确切大小，这对一些特殊的关系，比如Composition组合关系来讲是不好处理的。
我们在a.h中前置声明了class B，并将class A中的成员变量b改成一个指针，最后删掉#include "b.h"来打破这个递归包含关系，代码如下：
编译也顺利通过：
➜ v5 git:(master) ✗ g++ main.cc
利用前置声明，我找到了项目中某个Aggregation聚合关系的类（不需要我在头文件声明类的实体），相当于打断了这个包含关系环，如下：
这个问题到此就解决了，虽说解决方案有一定侵入性，但我觉得问题出现的本质应该是由语言特性和代码架构决定的，前置声明算是一种小小的解决办法吧。
参考
Google C++风格指南
c++ header files including each other mutually - Stack Overflow
博客中用到的代码我放在了我个人的GitHub中，读者们可以动手尝试一下。