Part11. 头文件

通常每一个 .cc文件都有一个对应的 .h文件.也有一些常见例外,如单元测试代码和只包含 main()函数的 .cc文件.正确使用头文件可令代码在可读性、文件大小和性能上大为改观. 下面的规则将引导你规避使用头文件时的各种陷阱.

1.1. Self-contained头文件

Tip: 头文件应该能够自给自足（self-contained,也就是可以作为第一个头文件被引入），以 .h结尾。至于用来插入文本的文件，说到底它们并不是头文件，所以应以 .inc结尾。不允许分离出 -inl.h头文件的做法.

所有头文件要能够自给自足。换言之，用户和重构工具不需要为特别场合而包含额外的头文件。详言之，一个头文件要有#define保护，统统包含它所需要的其它头文件，也不要求定义任何特别 symbols.不过有一个例外，即一个文件并不是 self-contained的，而是作为文本插入到代码某处。或者，文件内容实际上是其它头文件的特定平台（platform-specific）扩展部分。这些文件就要用 .inc文件扩展名。如果 .h文件声明了一个模板或内联函数，同时也在该文件加以定义。凡是有用到这些的 .cc文件，就得统统包含该头文件，否则程序可能会在构建中链接失败。不要把这些定义放到分离的 -inl.h文件里(译者注：过去该规范曾提倡把定义放到 -inl.h里过）。

有个例外：如果某函数模板为所有相关模板参数显式实例化，或本身就是某类的一个私有成员，那么它就只能定义在实例化该模板的 .cc文件里。

1.2. #define保护

Tip: 所有头文件都应该使用 #define 来防止头文件被多重包含, 命名格式当是:H

为保证唯一性,头文件的命名应该基于所在项目源代码树的全路径. 例如,项目 foo中的头文件 foo/ src/bar/baz.h可按如下方式保护:

#ifndef FOO_BAR_BAZ_H_
#define FOO_BAR_BAZ_H_
...
#endif // FOO_BAR_BAZ_H_

1.3.前置声明

Tip: 尽可能地避免使用前置声明。使用 #include包含需要的头文件即可。

定义：所谓「前置声明」（forward declaration）是类、函数和模板的纯粹声明，没伴随着其定义.优点：

前置声明能够节省编译时间，多余的 #include会迫使编译器展开更多的文件，处理更多的输入。
前置声明能够节省不必要的重新编译的时间。#include使代码因为头文件中无关的改动而被重新编译多次。

缺点：

前置声明隐藏了依赖关系，头文件改动时，用户的代码会跳过必要的重新编译过程。
前置声明可能会被库的后续更改所破坏。前置声明函数或模板有时会妨碍头文件开发者变动其 API.例如扩大形参类型，加个自带默认参数的模板形参等等。
前置声明来自命名空间 std::的 symbol时，其行为未定义。
很难判断什么时候该用前置声明，什么时候该用 #include。极端情况下，用前置声明代替 includes甚至都会暗暗地改变代码的含义：

// 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.

至于什么时候包含头文件，参见 # include的路径及顺序。

1.4.内联函数

Tip: 只有当函数只有 10行甚至更少时才将其定义为内联函数.

定义:当函数被声明为内联函数之后,编译器会将其内联展开,而不是按通常的函数调用机制进行调用.优点:只要内联的函数体较小,内联该函数可以令目标代码更加高效.对于存取函数以及其它函数体比较短,性能关键的函数,鼓励使用内联.缺点:滥用内联将导致程序变得更慢. 内联可能使目标代码量或增或减,这取决于内联函数的大小.内联非常短小的存取函数通常会减少代码大小,但内联一个相当大的函数将戏剧性的增加代码大小.现代处理器由于更好的利用了指令缓存,小巧的代码往往执行更快。结论: 一个较为合理的经验准则是,不要内联超过 10行的函数. 谨慎对待析构函数,析构函数往往比其表面看起来要更长,因为有隐含的成员和基类析构函数被调用!另一个实用的经验准则:内联那些包含循环或 switch语句的函数常常是得不偿失 (除非在大多数情况下,这些循环或 switch语句从不被执行).

有些函数即使声明为内联的也不一定会被编译器内联,这点很重要;比如虚函数和递归函数就不会被正常内联.通常,递归函数不应该声明成内联函数.（YuleFox注:递归调用堆栈的展开并不像循环那么简单,比如递归层数在编译时可能是未知的,大多数编译器都不支持内联递归函数).虚函数内联的主要原因则是想把它的函数体放在类定义内,为了图个方便,抑或是当作文档描述其行为,比如精短的存取函数.

1.5. #include的路径及顺序

Tip: 使用标准的头文件包含顺序可增强可读性,避免隐藏依赖:相关头文件, C库, C++库,其他库的 .h,本项目内的 .h.

项目内头文件应按照项目源代码目录树结构排列,避免使用 UNIX特殊的快捷目录 . (当前目录)或 ..(上级目录).例如, google-awesome-project/src/base/logging.h应该按如下方式包含:

#include "base/logging.h"

又如, dir/foo.cc或 dir/foo_test.cc的主要作用是实现或测试 dir2/foo2.h的功能, foo.cc中包含头文件的次序如下:

dir2/foo2.h (优先位置,详情如下)
C系统文件
C++系统文件
其他库的 .h文件
本项目内 .h文件

这种优先的顺序排序保证当 dir2/foo2.h遗漏某些必要的库时，dir/foo.cc或 dir/foo_test.cc的构建会立刻中止。因此这一条规则保证维护这些文件的人们首先看到构建中止的消息而不是维护其他包的人们。

dir/foo.cc 和 dir2/foo2.h 通常位于同一目录下 (如 base/basictypes_unittest.cc 和 base/ basictypes.h),但也可以放在不同目录下.

按字母顺序分别对每种类型的头文件进行二次排序是不错的主意。注意较老的代码可不符合这条规则，要在方便的时候改正它们。

您所依赖的符号 (symbols)被哪些头文件所定义，您就应该包含（include）哪些头文件，前置声明 (forward declarations)情况除外。比如您要用到 bar.h中的某个符号,哪怕您所包含的 foo.h已经包含了 bar.h, 也照样得包含 bar.h,除非 foo.h有明确说明它会自动向您提供 bar.h中的 symbol.不过，凡是 cc文件所对应的「相关头文件」已经包含的，就不用再重复包含进其 cc文件里面了，就像 foo.cc只包含 foo.h就够了，不用再管后者所包含的其它内容。

举例来说, google-awesome-project/src/foo/internal/fooserver.cc的包含次序如下:

#include "foo/public/fooserver.h" //优先位置

#include <sys/types.h>
#include <unistd.h>

#include <hash_map>
#include <vector>

#include "base/basictypes.h"
#include "base/commandlineflags.h"
#include "foo/public/bar.h"

例外：有时，平台特定（system-specific）代码需要条件编译（conditional includes），这些代码可以放到其它 includes之后。当然，您的平台特定代码也要够简练且独立，比如：

#include "foo/public/fooserver.h"

#include "base/port.h" // For LANG_CXX11.

#ifdef LANG_CXX11
#include <initializer_list>
#endif // LANG_CXX11

note：