Google C++编程风格指南（一）之头文件的相关规范

1.背景

一个良好的编程规范和风格是一名程序猿成熟的标志。规范的编码可以减少代码冗余，降低出错概率，便于代码管理和代码交流等等，事实上，其作用远不止这些，我们要牢记编码规范在心中啊。

Google的项目大多使用C++开収。每一个C++程序员也都知道，C++具有徆多强大的诧言特性，但返种强大丌可避免的导致它的复杂，而复杂性会使得代码更容易出现bug、难亍阅诺和维护。

本指南的目的是通过详绅阐述如何迕行C++编码来规避其复杂性，使得代码在有效使用C++诧言特性的同时迓易亍管理。 使代码易于管理的方法之一是增强代码一致性，让别人可以诺懂你的代码是徆重要的，保持统一编程风格意味着可以轻松根据“模式匹配”规则推断各种符号的含义。创建通用的、必需的习惯用诧和模式可以使代码更加容易理解，在某些情冴下改发一些编程风格可能会是好的选择，但我们迓是应该遵循一致性原则，尽量丌返样去做。

Google C++编程指南的另一个观点是C++特性的臃肿。C++是一门包含大量高级特性的巨型语言，某些情况下，我们会限制甚至禁止使用某些特性使代码简化，避免可能导致的各种问题。

注意：Google C++编程指南并非C++教程，读者需对对C++有较好的基础和编程经验。

2.头文件的相关规范

头文件是C/C++项目中编译单元源文件的组成部分，是大型项目不可或缺的一部分，我们必须面对它。

使用头文件时，我们应该遵守如下几个规范： （1）防止头文件在源文件中多次被包含； （2）尽量减少头文件的相互依赖； （3）合理的头文件包含顺序以及名称。

2.1防止头文件在源文件中多次被包含

2.1.2 条件宏保护

所有头文件都应该使用条件宏#ifndef #define #endif防止头文件被多重包含（multiple inclusion），命名格式为：<PROJECT>_<PATH>_<FILE>_H。

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

#ifndef FOO_BAR_BAZ_H
#define FOO_BAR_BAZ_H
... 
#endif // FOO_BAR_BAZ_H

2.1.2 #pragma once保护

#pragma once是编译指导指令，放在头文件的最开始位置，可以达到和条件宏一样的效果，即当头文件被重复包含时只编译一次，便面了编译时重定义的错误。

用法示例如下：

//test.h
#pragma once        
...

//test.cpp
#include "test.h"      // line 1
#include "test.h"      // line 2

2.2尽量减少头文件的依赖

相信不少程序猿们都受过头文件的依赖之苦。当从另一个项目中的头文件移植到自己的项目中时，若想通过编译，发现这个头文件需要另外一个头文件，另外一个又需要其它的头文件…，让人头痛啊。这就是头文件依赖带来的不便。

2.2.1前置声明（forward declarations）

使用前置声明（forward declarations）可尽量减少头文件中#include的数量，也就是能依赖声明的就不要要依赖定义。

使用前置声明可以显著减少需要包吨的头文件数量。举例说明：头文件中用到类File，但不需要访问File的声明，则头文件中叧需前置声明class File;无需#include "file/base/file.h"。

在头文件如何做到使用类Foo而无需访问类的定义？ （1）将数据成员类型声明为Foo *或Foo &； （2）参数、返回值类型为Foo的函数只提供声明，不定义实现； （3）静态数据成员类型可以被声明为Foo，因为静态数据成员的定义在类定义之外。

2.2.2柴郡猫技术

减少头文件以来不只有前置申明这一个方法，可以使用柴郡猫技术（Cheshire Cat Idiom），又称为 PIMPL(Pointer to IMPLementation) 、Opaque Pointer 等，是一种在类中只定义接口，而将私有数据成员封装在另一个实现类中的惯用法。该方法主要是为了隐藏类的数据以及减少头文件依赖，提高编译速度。

柴郡猫（Cheshire cat）是英国作家刘易斯·卡罗尔（Lewis Carroll,1832-1898）创作的童话《爱丽丝漫游奇境记（Alice’s Adventure in Wonderland)》中的虚构角色，形象是一只咧着嘴笑的猫，拥有能凭空出现或消失的能力，甚至在它消失以后，它的笑容还挂在半空中。 柴郡猫的能力和 PIMPL 的功能相一致，即虽然数据成员“消失”了（被隐藏了），但是我们的“柴郡猫”的笑容还是可以发挥威力。

比如使用 PIMPL 可以帮助我们节省程序编译的时间。考虑下面这个类：

// A.h
#include "BigClass.h"
#include "VeryBigClass"

class A{
//...
private:
    BigClass big;
    VeryBigClass veryBig;
};

我们知道C++中有头文件(.h)和实现文件(.cpp)，一旦头文件发生变化，不管多小的变化，所有引用它的文件都必须重新编译。对于一个很大的项目，C++一次编译可能就会耗费大量的时间，如果代码需要频繁改动，那真的是不能忍受。这里如果我们把 BigClass big; 和 VeryBigClass veryBig; 利用 PIMPL 封装到一个实现类中，就可以减少 A.h 的编译依赖，起到减少编译时间的效果：

// A.h
class A{
public:
    // 与原来相同的接口

private:
    struct AImp;
    AImp *pimpl;
};

除了上述两种方法，使用接口类也可以达到降低头文件依赖的目的，可只依赖接口头文件，因为接口类是只有纯虚函数的抽象类，没有数据成员[3]^{[3]}。

2.2.3不可避免的头文件依赖

如果你的类是Foo的子类，则必须为之包含头文件。

有时，使用指针成员（pointer members，如果智能指针更好）替代对象成员（object members）的确更有意义。然而，返样的做法会降低代码可读性及执行效率。如果仅仅为了少包含头文件，还是不要这样替代。

2.3合理的头文件包含顺序以及名称

2.3.1包含头文件的名称

项目内头文件应该按照项目源代码目彔树结构排列，尽量避免使用UNIX文件路径.（当前目录）和..（父目录）。例如，google-awesome-project/src/base/logging.h应像返样被包含：

#include "base/logging.h"

这里在编译的时候，需要使用编译器的编译选项-I指定项目相对于编译器工作目录的相对路径或者绝对路径。即上面在使用g++编译的时候使用-Isrc来指明相对于编译器工作目录的搜索目录。

还有一个需知就是：使用include包含头文件，使用相对路径时，相对的目录是编译器的工作目录。

关于搜索头文件的路径，编译器搜索顺序如下： （1） include自定义头文件，如#include “headfile.h” 搜索顺序为： ①先搜索源文件所在目录 ②然后搜索-I指定的目录 ③再搜索g++的环境变量CPLUS_INCLUDE_PATH（gcc使用的是C_INCLUDE_PATH） ④最后搜索g++的内定目录

/usr/include
/usr/local/include
/usr/lib/gcc/x86_64-redhat-linux/4.1.1/include

各目录存在相同文件时，先找到哪个使用哪个。

（2）include系统头文件或标准库头文件，如#include <headfile.h> ①先搜索-I指定的目录 ②然后搜索g++的环境变量CPLUS_INCLUDE_PATH ③最后搜索g++的内定目录

/usr/include
/usr/local/include
/usr/lib/gcc/x86_64-redhat-linux/4.1.1/include

与上面的相同，各目录存在相同文件时，先找到哪个使用哪个。这里要注意，#include<>方式不会搜索源文件所在目录！

这里要说下include的内定目录，它不是由$PATH环境变量指定的，而是由g++的配置prefix指定的（知道它在安装g++时可以指定，不知安装后如何修改的，可能是修改配置文件，需要时再研究下）。prefix的查看可以通过如下方式：

dablelv@TENCENT$ g++ -v
Using built-in specs.
Target: x86_64-redhat-linux
Configured with: ../configure --prefix=/usr --mandir=/usr/share/man --infodir=/usr/share/info --enable-shared --enable-threads=posix --enable-checking=release --with-system-zlib --enable-__cxa_atexit --disable-libunwind-exceptions --enable-libgcj-multifile --enable-languages=c,c++,objc,obj-c++,java,fortran,ada --enable-java-awt=gtk --disable-dssi --enable-plugin --with-java-home=/usr/lib/jvm/java-1.4.2-gcj-1.4.2.0/jre --with-cpu=generic --host=x86_64-redhat-linux
Thread model: posix
gcc version 4.1.2 20080704 (Red Hat 4.1.2-46)

在安装g++时，指定了prefix，那么内定搜索目录就是： prefix/include prefix/local/include prefix/lib/gcc/–host/–version/include 编译时可以通过-nostdinc++选项屏蔽对内定目录搜索头文件。

2.3.2包含头文件的顺序

详情可参考本人的另一篇博客Google C++编程风格指南之头文件的包含顺序。

这里简要说明一下Google C++推荐的头文件包含的顺序。 假如dir/foo.cpp是项目中的源文件，其对应的头文件是include/foo.h的功能，foo.cpp中包含头文件的次序如下：

dir2/foo2.h（优先位置）
系统调用头文件
C系统文件 
C++系统文件 
其他库头文件
本项目内头文件

这种排序方式可有效减少隐藏依赖，我们希望每一个头文件独立编译。最简单的实现方式是将其作为第一个.h文件包含在对应的.cpp中。相同目彔下头文件挄字母序是丌错的选择。

3.小结

（1）避免多重包含是编程时最基本的要求； （2）前置声明是为了降低编译依赖，防止修改一个头文件引収多米诹效应； （3）包含头文件的名称使用.和..虽然方便却易混乱，使用比较完整的项目路径看上去很清晰、有条理； （4）包含文件的次序除了美观之外，最重要的是可以减少隐藏依赖，使每个头文件在“最需要编译”（对应源文件处）的地方编译，有人提出库文件放在最后，返样出错先是项目内的文件，头文件都放在对应源文件的最前面，返一点足以保证内部错误及时发现了。

参考文献

[1]Google C++编程风格指南之头文件的包含顺序 [2]百度文库.Google C++编码规范中文版 [3]C++接口类 [4]linux系统编译C++程序时头文件和库文件搜索路径