0. 扉页 Google 开源项目风格指南 http:/zh-google-styleguide.readthedocs.org/en/latest/google-cpp-styleguide/2014-1-9 15:24:56 C+ 风格指南 - 内容目录 : Contents : 1. 头文件 0. 扉页 版本:3.133 原作者:Benjy Weinberger Craig Silverstein Gregory Eitzmann Mark Mentovai Tashana Landray 翻译:YuleFox brantyoung 项目主页: Google Style Guide Google 开源项目风格指南 - 中文版 0.1 译者前言 Google 经常会发布一些开源项目, 意味着会接受来自其他代码贡献者的代码. 但是如果代码贡献者的编程风格与 Google 的不一致, 会给代码 阅读者和其他代码提交这造成不小的困扰. Google 因此发布了这份自己的编程风格, 使所有提交代码的人都能获知 Google 的编程风格. 翻译初衷: 规则的作用就是避免混乱. 但规则本身一定要权威, 有说服力, 并且是理性的. 我们所见过的大部分编程规范, 其内容或不够严谨, 或阐述过 于简单, 或带有一定的武断性. Google 保持其一贯的严谨精神, 5 万汉字的指南涉及广泛, 论证严密. 我们翻译该系列指南的主因也正是其严谨性. 严谨意味着指南的价 值不仅仅局限于它罗列出的规范, 更具参考意义的是它为了列出规范而做的谨慎权衡过程. 指南不仅列出你要怎么做, 还告诉你为什么要这么做, 哪些情况下可以不这么做, 以及如何权衡其利弊. 其他团队未必要完全遵照指南亦步 亦趋, 如前面所说, 这份指南是 Google 根据自身实际情况打造的, 适用于其主导的开源项目. 其他团队可以参照该指南, 或从中汲取灵感, 建立适合自身实际情况的规范. 我们在翻译的过程中, 收获颇多. 希望本系列指南中文版对你同样能有所帮助. 我们翻译时也是尽力保持严谨, 但水平所限, bug 在所难免. 有任何意见或建议, 可与我们取得联系. 中文版和英文版一样, 使用 Artistic License/GPL 开源许可. 中文版修订历史: 2009-06 3.133 : YuleFox 的 1.0 版已经相当完善, 但原版在近一年的时间里, 其规范也发生了一些变化. brantyoung 与 YuleFox 一拍即合, 以项目的形式来延续中文版 : Google 开源项目风格指南 - 中文版项目. 主要变化是同步到 3.133 最新英文版本, 做部分勘误和改善可读性方面的修改, 并改进排版效果. brantyoung 重新翻修, YuleFox 做后续评审. 2008-07 1.0 : 出自 YuleFox 的 Blog, 很多地方摘录的也是该版本. 0.2 背景 C+ 是 Google 大部分开源项目的主要编程语言. 正如每个 C+ 程序员都知道的, C+ 有很多强大的特性, 但这种强大不可避免的导致它走向 复杂，使代码更容易产生 bug, 难以阅读和维护. Google 开源项目风格指南 0. 扉页 0. 扉页 Google 开源项目风格指南 http:/zh-google-styleguide.readthedocs.org/en/latest/google-cpp-styleguide/2014-1-9 15:24:56 本指南的目的是通过详细阐述 C+ 注意事项来驾驭其复杂性. 这些规则在保证代码易于管理的同时, 高效使用 C+ 的语言特性. 风格, 亦被称作可读性, 也就是指导 C+ 编程的约定. 使用术语 “风格” 有些用词不当, 因为这些习惯远不止源代码文件格式化这么简单. 使代码易于管理的方法之一是加强代码一致性. 让任何程序员都可以快速读懂你的代码这点非常重要. 保持统一编程风格并遵守约定意味着可 以很容易根据 “模式匹配” 规则来推断各种标识符的含义. 创建通用, 必需的习惯用语和模式可以使代码更容易理解. 在一些情况下可能有充分 的理由改变某些编程风格, 但我们还是应该遵循一致性原则，尽量不这么做. 本指南的另一个观点是 C+ 特性的臃肿. C+ 是一门包含大量高级特性的庞大语言. 某些情况下, 我们会限制甚至禁止使用某些特性. 这么做 是为了保持代码清爽, 避免这些特性可能导致的各种问题. 指南中列举了这类特性, 并解释为什么这些特性被限制使用. Google 主导的开源项目均符合本指南的规定. 注意: 本指南并非 C+ 教程, 我们假定读者已经对 C+ 非常熟悉. C+ 风格指南 - 内容目录 : Contents : 1. 头文件 Copyright . Created using Sphinx 1.1.3. 1. 头文件 Google 开源项目风格指南 http:/zh-google-styleguide.readthedocs.org/en/latest/google-cpp-styleguide/headers/2014-1-9 15:25:20 0. 扉页 : Contents : 2. 作用域 1. 头文件 通常每一个 .cc 文件都有一个对应的 .h 文件. 也有一些常见例外, 如单元测试代码和只包含 main() 函数的 .cc 文件. 正确使用头文件可令代码在可读性、文件大小和性能上大为改观. 下面的规则将引导你规避使用头文件时的各种陷阱. 1.1. #define 保护 Tip 所有头文件都应该使用 #define 防止头文件被多重包含, 命名格式当是: _H_ 为保证唯一性, 头文件的命名应该依据所在项目源代码树的全路径. 例如, 项目 foo 中的头文件 foo/src/bar/baz.h 可按如下方式保护: 1.2. 头文件依赖 Tip 能用前置声明的地方尽量不使用 #include. 当一个头文件被包含的同时也引入了新的依赖, 一旦该头文件被修改, 代码就会被重新编译. 如果这个头文件又包含了其他头文件, 这些头文件 的任何改变都将导致所有包含了该头文件的代码被重新编译. 因此, 我们倾向于减少包含头文件, 尤其是在头文件中包含头文件. 使用前置声明可以显著减少需要包含的头文件数量. 举例说明: 如果头文件中用到类 File, 但不需要访问 File 类的声明, 头文件中只需前置声 明 class File; 而无须 #include “file/base/file.h“. 不允许访问类的定义的前提下, 我们在一个头文件中能对类 Foo 做哪些操作? 我们可以将数据成员类型声明为 Foo * 或 Foo 比如虚函数和递归函数就不会被正常内联. 通常, 递归函数不应该声明 成内联函数.（YuleFox 注: 递归调用堆栈的展开并不像循环那么简单, 比如递归层数在编译时可能是未知的, 大多数编译器都不支持内联 递归函数). 虚函数内联的主要原因则是想把它的函数体放在类定义内, 为了图个方便, 抑或是当作文档描述其行为, 比如精短的存取函数. 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. 头文件 Google 开源项目风格指南 http:/zh-google-styleguide.readthedocs.org/en/latest/google-cpp-styleguide/headers/2014-1-9 15:25:20 这条规则并不需要严格遵守. 输入/输出两用参数 (通常是类/结构体变量) 把事情变得复杂, 为保持和相关函数的一致性, 你有时不得不有所变 通. 1.6. #include 的路径及顺序 Tip 使用标准的头文件包含顺序可增强可读性, 避免隐藏依赖: C 库, C+ 库, 其他库的 .h, 本项目内的 .h. 项目内头文件应按照项目源代码目录树结构排列, 避免使用 UNIX 特殊的快捷目录 . (当前目录) 或 (上级目录). 例如, google-awesome- project/src/base/logging.h 应该按如下方式包含: 又如, dir/foo.cc 的主要作用是实现或测试 dir2/foo2.h 的功能, foo.cc 中包含头文件的次序如下: 1. dir2/foo2.h (优先位置, 详情如下) 2. C 系统文件 3. C+ 系统文件 4. 其他库的 .h 文件 5. 本项目内 .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 的包含次序如下: 译者 (YuleFox) 笔记 1. 避免多重包含是学编程时最基本的要求; 2. 前置声明是为了降低编译依赖，防止修改一个头文件引发多米诺效应; 3. 内联函数的合理使用可提高代码执行效率; 4. -inl.h 可提高代码可读性 (一般用不到吧:D); 5. 标准化函数参数顺序可以提高可读性和易维护性 (对函数参数的堆栈空间有轻微影响, 我以前大多是相同类型放在一起); 6. 包含文件的名称使用 . 和 虽然方便却易混乱, 使用比较完整的项目路径看上去很清晰, 很条理, 包含文件的次序除了美观之外, 最重要的 是可以减少隐藏依赖, 使每个头文件在 “最需要编译” (对应源文件处 :D) 的地方编译, 有人提出库文件放在最后, 这样出错先是项目内的文 件, 头文件都放在对应源文件的最前面, 这一点足以保证内部错误的及时发现了. 0. 扉页 : Contents : 2. 作用域 Copyright . Created using Sphinx 1.1.3. #include “b