1. 头文件
------------

通常每一个 ``.cc`` 文件都有一个对应的 ``.h`` 文件. 也有一些常见例外, 如单元测试代码和只包含 ``main()`` 函数的 ``.cc`` 文件.

正确使用头文件可令代码在可读性、文件大小和性能上大为改观.

下面的规则将引导你规避使用头文件时的各种陷阱.

.. _define_guard:

1.1. #define 保护
~~~~~~~~~~~~~~~~~~~~

.. tip::
   所有头文件都应该使用 ``#define`` 防止头文件被多重包含, 命名格式当是: ``<PROJECT>_<PATH>_<FILE>_H_``

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

.. code-block:: c++

    #ifndef FOO_BAR_BAZ_H_
    #define FOO_BAR_BAZ_H_
    …
    #endif // FOO_BAR_BAZ_H_


1.2. 头文件依赖
~~~~~~~~~~~~~~~~~~~~

.. tip::
   能用前置声明的地方尽量不使用 ``#include``.

当一个头文件被包含的同时也引入了新的依赖, 一旦该头文件被修改, 代码就会被重新编译. 如果这个头文件又包含了其他头文件, 这些头文件的任何改变都将导致所有包含了该头文件的代码被重新编译. 因此, 我们倾向于减少包含头文件, 尤其是在头文件中包含头文件.

使用前置声明可以显著减少需要包含的头文件数量. 举例说明: 如果头文件中用到类 ``File``, 但不需要访问 ``File`` 类的声明, 头文件中只需前置声明 ``class File;`` 而无须 ``#include "file/base/file.h"``.

不允许访问类的定义的前提下, 我们在一个头文件中能对类 ``Foo`` 做哪些操作?

- 我们可以将数据成员类型声明为 ``Foo *`` 或 ``Foo &``.
- 我们可以将函数参数 / 返回值的类型声明为 ``Foo`` (但不能定义实现).
- 我们可以将静态数据成员的类型声明为 ``Foo``, 因为静态数据成员的定义在类定义之外.

反之, 如果你的类是 ``Foo`` 的子类, 或者含有类型为 ``Foo`` 的非静态数据成员, 则必须包含 ``Foo`` 所在的头文件.

有时, 使用指针成员 (如果是 ``scoped_ptr`` 更好) 替代对象成员的确是明智之选. 然而, 这会降低代码可读性及执行效率, 因此如果仅仅为了少包含头文件，还是不要这么做的好.

当然 ``.cc`` 文件无论如何都需要所使用类的定义部分, 自然也就会包含若干头文件.


.. _inline-functions:

1.3. 内联函数
~~~~~~~~~~~~~~~~~~~~

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

定义:
    当函数被声明为内联函数之后, 编译器会将其内联展开, 而不是按通常的函数调用机制进行调用.

优点:
    当函数体比较小的时候, 内联该函数可以令目标代码更加高效. 对于存取函数以及其它函数体比较短, 性能关键的函数, 鼓励使用内联.

缺点:
    滥用内联将导致程序变慢. 内联可能使目标代码量或增或减, 这取决于内联函数的大小. 内联非常短小的存取函数通常会减少代码大小, 但内联一个相当大的函数将戏剧性的增加代码大小. 现代处理器由于更好的利用了指令缓存, 小巧的代码往往执行更快。

结论:
    一个较为合理的经验准则是, 不要内联超过 10 行的函数. 谨慎对待析构函数, 析构函数往往比其表面看起来要更长, 因为有隐含的成员和基类析构函数被调用!
    
    另一个实用的经验准则: 内联那些包含循环或 ``switch`` 语句的函数常常是得不偿失 (除非在大多数情况下, 这些循环或 ``switch`` 语句从不被执行).
    
    有些函数即使声明为内联的也不一定会被编译器内联, 这点很重要; 比如虚函数和递归函数就不会被正常内联.  通常, 递归函数不应该声明成内联函数.（YuleFox 注: 递归调用堆栈的展开并不像循环那么简单, 比如递归层数在编译时可能是未知的, 大多数编译器都不支持内联递归函数). 虚函数内联的主要原因则是想把它的函数体放在类定义内, 为了图个方便, 抑或是当作文档描述其行为, 比如精短的存取函数.


.. _inl-files:

1.4. -inl.h文件
~~~~~~~~~~~~~~~~~~~~

.. tip::
    复杂的内联函数的定义, 应放在后缀名为 ``-inl.h`` 的头文件中.

内联函数的定义必须放在头文件中, 编译器才能在调用点内联展开定义. 然而, 实现代码理论上应该放在 ``.cc`` 文件中, 我们不希望 ``.h`` 文件中有太多实现代码, 除非在可读性和性能上有明显优势.

如果内联函数的定义比较短小, 逻辑比较简单, 实现代码放在 ``.h`` 文件里没有任何问题. 比如, 存取函数的实现理所当然都应该放在类定义内. 出于编写者和调用者的方便, 较复杂的内联函数也可以放到 ``.h`` 文件中, 如果你觉得这样会使头文件显得笨重, 也可以把它萃取到单独的 ``-inl.h`` 中. 这样把实现和类定义分离开来, 当需要时包含对应的 ``-inl.h`` 即可。

``-inl.h`` 文件还可用于函数模板的定义. 从而增强模板定义的可读性.

别忘了 ``-inl.h`` 和其他头文件一样, 也需要 ``#define`` 保护.

1.5. 函数参数的顺序
~~~~~~~~~~~~~~~~~~~~

.. tip::
    定义函数时, 参数顺序依次为: 输入参数, 然后是输出参数.

C/C++ 函数参数分为输入参数, 输出参数, 和输入/输出参数三种. 输入参数一般传值或传 ``const`` 引用, 输出参数或输入/输出参数则是非-``const`` 指针. 对参数排序时, 将只输入的参数放在所有输出参数之前. 尤其是不要仅仅因为是新加的参数, 就把它放在最后; 即使是新加的只输入参数也要放在输出参数之前.

这条规则并不需要严格遵守. 输入/输出两用参数 (通常是类/结构体变量) 把事情变得复杂, 为保持和相关函数的一致性, 你有时不得不有所变通.

1.6. ``#include`` 的路径及顺序
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

又如, ``dir/foo.cc`` 的主要作用是实现或测试 ``dir2/foo2.h`` 的功能, ``foo.cc`` 中包含头文件的次序如下:
    #. ``dir2/foo2.h`` (优先位置, 详情如下)
    #. C 系统文件
    #. C++ 系统文件
    #. 其他库的 ``.h`` 文件
    #. 本项目内 ``.h`` 文件

这种排序方式可有效减少隐藏依赖. 我们希望每一个头文件都是可被独立编译的 (yospaly 译注: 即该头文件本身已包含所有必要的显式依赖), 最简单的方法是将其作为第一个 ``.h`` 文件 ``#included`` 进对应的 ``.cc``.

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

按字母顺序对头文件包含进行二次排序是不错的主意 (yospaly 译注: 之前已经按头文件类别排过序了).

举例来说, ``google-awesome-project/src/foo/internal/fooserver.cc`` 的包含次序如下:
    .. code-block:: c++
        
        #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"

译者 (YuleFox) 笔记
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. 避免多重包含是学编程时最基本的要求;
#. 前置声明是为了降低编译依赖，防止修改一个头文件引发多米诺效应;
#. 内联函数的合理使用可提高代码执行效率;
#. ``-inl.h`` 可提高代码可读性 (一般用不到吧:D);
#. 标准化函数参数顺序可以提高可读性和易维护性 (对函数参数的堆栈空间有轻微影响, 我以前大多是相同类型放在一起);
#. 包含文件的名称使用 ``.`` 和 ``..`` 虽然方便却易混乱, 使用比较完整的项目路径看上去很清晰, 很条理, 包含文件的次序除了美观之外, 最重要的是可以减少隐藏依赖, 使每个头文件在 "最需要编译" (对应源文件处 :D) 的地方编译, 有人提出库文件放在最后, 这样出错先是项目内的文件, 头文件都放在对应源文件的最前面, 这一点足以保证内部错误的及时发现了.