CHAPTER 2C++风格指南-内容目录ContentsC++风格指南-内容目录.2.10.页版本4.45原作者Benjy WeinbergerCraig SilversteinGregoryEitzmannMark MentovaiTashana Landray翻译YuleFoxYang.Yacgtyrantlilinsanity项目主页:Google Style Guide3
CHAPTER 2 C++ 风格指南 - 内容目录 Contents • C++ 风格指南 - 内容目录 2.1 0. 扉页 版本 4.45 原作者 Benjy Weinberger Craig Silverstein Gregory Eitzmann Mark Mentovai Tashana Landray 翻译 YuleFox Yang.Y acgtyrant lilinsanity 项目主页 • Google Style Guide 3
Google开源项目风格指南·Google开源项目风格指南-中文版2.1.1 0.1 译者前言Google经常会发布一些开源项目，意味着会接受来自其他代码贡献者的代码．但是如果代码贡献者的编程风格与Google的不一致，会给代码阅读者和其他代码提交者造成不小的困扰.Google因此发布了这伤自已的编程风格指南，使所有提交代码的人都能获知Google的编程风格翻译初衷：规则的作用就是避免混乱，但规则本身一定要权威，有说服力，并且是理性的，我们所见过的大部分编程规范，其内容或不够严谨，或阐述过于简单，或带有一定的武断性Google保持其一贯的严谨精神，5万汉字的指南涉及广泛，论证严密我们翻译该系列指南的主因也正是其严谨性：严谨意味着指南的价值不仅仅局限于它罗列出的规范，更具参考意义的是它为了列出规范而做的谨慎权衡过程，指南不仅列出你要怎么做，还告诉你为什么要这么做，哪些情况下可以不这么做，以及如何权衡其利.其他团队未必要完全遵照指南亦步亦趋，如前面所说，这份指南是Google根据自身实际情况打造的，适用于其主导的开源项目，其他团队可以参照该指南，或从中汲取灵感，建立适合自身实际情况的规范我们在翻译的过程中，收获颇多.希望本系列指南中文版对你同样能有所帮助我们翻译时也是尽力保持严谨，但水平所限，bug在所难免，有任何意见或建议，可与我们取得联系中文版和英文版一样，使用ArtisticLicense/GPL开源许可，中文版修订历史：·2015-08：热心的清华大学同学@lilinsanity完善了「类」章节以及其它一些小章节。至此，对GoogleCPPStyleGuide4.45的翻译正式竣工。·2015-074.45：acgtyrant为了学习C++的规范，顺便重新翻译了本C++风格指南，特别是C++11的全新内容。排版大幅度优化，翻译措辞更地道，添加了新译者笔记。Google总部C++工程师innocentim，清华大学不愿意透露姓名的唐马儒先生，大阪大学大学院情报科学研究科计算机科学专攻博士farseerfc和其它ArchLinux中文社区众帮了译者不少忙，谢谢他们。因为C++Primer尚未完全入门，暂时没有翻译「类」章节和其它一些小章节。·2009-063.133：YuleFox的1.0版已经相当完善，但原版在近一年的时间里，其规范也发生了一些变化.Yang.Y与YuleFox一拍即合，以项目的形式来延续中文版：Google开源项目风格指南中文版项目主要变化是同步到3.133最新英文版本，做部分勘误和改善可读性方面的修改，并改进排版效果.Yang.Y重新翻修，YuleFox做后续评审·2008-071.0：出自YuleFox的Blog，很多地方摘录的也是该版本4Chapter2.C++风格指南-内容目录
Google 开源项目风格指南 • Google 开源项目风格指南 - 中文版 2.1.1 0.1 译者前言 Google 经常会发布一些开源项目, 意味着会接受来自其他代码贡献者的代码. 但是如果代码贡献者的编 程风格与 Google 的不一致, 会给代码阅读者和其他代码提交者造成不小的困扰. Google 因此发布了这份 自己的编程风格指南, 使所有提交代码的人都能获知 Google 的编程风格. 翻译初衷: 规则的作用就是避免混乱. 但规则本身一定要权威, 有说服力, 并且是理性的. 我们所见过的 大部分编程规范, 其内容或不够严谨, 或阐述过于简单, 或带有一定的武断性. Google 保持其一贯的严谨精神, 5 万汉字的指南涉及广泛, 论证严密. 我们翻译该系列指南的 主因也正是其严谨性. 严谨意味着指南的价值不仅仅局限于它罗列出的规范, 更具参考意义的 是它为了列出规范而做的谨慎权衡过程. 指南不仅列出你要怎么做, 还告诉你为什么要这么做, 哪些情况下可以不这么做, 以及如何权 衡其利弊. 其他团队未必要完全遵照指南亦步亦趋, 如前面所说, 这份指南是 Google 根据自 身实际情况打造的, 适用于其主导的开源项目. 其他团队可以参照该指南, 或从中汲取灵感, 建立适合自身实际情况的规范. 我们在翻译的过程中, 收获颇多. 希望本系列指南中文版对你同样能有所帮助. 我们翻译时也是尽力保持严谨, 但水平所限, bug 在所难免. 有任何意见或建议, 可与我们取得联系. 中文版和英文版一样, 使用 Artistic License/GPL 开源许可. 中文版修订历史: • 2015-08 : 热心的清华大学同学 @lilinsanity 完善了「类」章节以及其它一些小章节。至此，对 Google CPP Style Guide 4.45 的翻译正式竣工。 • 2015-07 4.45 : acgtyrant 为了学习 C++ 的规范，顺便重新翻译了本 C++ 风格指南，特别是 C++11 的全新内容。排版大幅度优化，翻译措辞更地道，添加了新译者笔记。Google 总部 C++ 工程师 innocentim, 清华大学不愿意透露姓名的唐马儒先生，大阪大学大学院情报科学研究科计算机科学 专攻博士 farseerfc 和其它 Arch Linux 中文社区众帮了译者不少忙，谢谢他们。因为 C++ Primer 尚未完全入门，暂时没有翻译「类」章节和其它一些小章节。 • 2009-06 3.133 : YuleFox 的 1.0 版已经相当完善, 但原版在近一年的时间里, 其规范也发生了一些变 化. Yang.Y 与 YuleFox 一拍即合, 以项目的形式来延续中文版: Google 开源项目风格指南 - 中文版项目. 主要变化是同步到 3.133 最新英文版本, 做部分勘误和改善可读性方面的修改, 并改进排 版效果. Yang.Y 重新翻修, YuleFox 做后续评审. • 2008-07 1.0 : 出自 YuleFox 的 Blog, 很多地方摘录的也是该版本. 4 Chapter 2. C++ 风格指南 - 内容目录
Google开源项目风格指南2.1.20.2背景C++是Google大部分开源项目的主要编程语言.正如每个C++程序员都知道的，C++有很多强大的特性，但这种强大不可避免的导致它走向复杂，使代码更容易产生bug，难以阅读和维护本指南的目的是通过详细阐述C++注意事项来驾驭其复杂性这些规则在保证代码易于管理的同时，也能高效使用C++的语言特性风格，亦被称作可读性，也就是指导C++编程的约定.使用术语“风格”有些用词不当，因为这些习惯远不止源代码文件格式化这么简单，使代码易于管理的方法之一是加强代码一致性。让任何程序员都可以快速读懂你的代码这点非常重要保持统一编程风格并遵守约定意味着可以很容易根据“模式匹配”规则来推断各种标识符的含义.创建通用，必需的习惯用语和模式可以使代码更容易理解。在一些情况下可能有充分的理由改变某些编程风格但我们还是应该遵循一致性原则，尽量不这么做，本指南的另一个观点是C++特性的臃肿：C++是一门包含大量高级特性的庞大语言：某些情况下，我们会限制甚至禁止使用某些特性这么做是为了保持代码清爽，避免这些特性可能导致的各种问题。指南中列举了这类特性，并解释为什么这些特性被限制使用Google主导的开源项目均符合本指南的规定，注意：本指南并非C++教程，我们假定读者已经对C++非常熟悉2.21.头文件通常每一个.cc文件都有一个对应的.h文件也有一些常见例外，如单元测试代码和只包含main）函数的.cc文件.正确使用头文件可令代码在可读性、文件大小和性能上大为改观下面的规则将引导你规避使用头文件时的各种陷阱2.2.11.1.Self-contained头文件Tip：头文件应该能够自给自足（self-contained，也就是可以作为第一个头文件被引入），以.h结尾。至于用来插人文本的文件，说到底它们并不是头文件，所以应以inc结尾。不充许分离出-inl.h头文件的做法所有头文件要能够自给自足。换言之，用户和重构工具不需要为特别场合而包含额外的头文件。详言之一个头文件要有1.2.#define保护，统统包含它所需要的其它头文件，也不要求定义任何特别symbols不过有一个例外，即一个文件并不是self-contained的，而是作为文本插入到代码某处。或者，文件内容实际上是其它头文件的特定平台（platform-specific）扩展部分。这些文件就要用.inc文件扩展名。如果.h文件声明了一个模板或内联函数，同时也在该文件加以定义。凡是有用到这些的：cc文件，就得统统包含该头文件，否则程序可能会在构建中链接失败。不要把这些定义放到分离的-i1.h文件里（译者注：过去该规范曾提倡把定义放到-inl.h里过）。52.2.1.头文件
Google 开源项目风格指南 2.1.2 0.2 背景 C++ 是 Google 大部分开源项目的主要编程语言. 正如每个 C++ 程序员都知道的, C++ 有很多强大的 特性, 但这种强大不可避免的导致它走向复杂，使代码更容易产生 bug, 难以阅读和维护. 本指南的目的是通过详细阐述 C++ 注意事项来驾驭其复杂性. 这些规则在保证代码易于管理的同时, 也 能高效使用 C++ 的语言特性. 风格, 亦被称作可读性, 也就是指导 C++ 编程的约定. 使用术语“风格”有些用词不当, 因为这些习惯远 不止源代码文件格式化这么简单. 使代码易于管理的方法之一是加强代码一致性. 让任何程序员都可以快速读懂你的代码这点非常重要. 保持统一编程风格并遵守约定意味着可以很容易根据“模式匹配”规则来推断各种标识符的含义. 创建通 用, 必需的习惯用语和模式可以使代码更容易理解. 在一些情况下可能有充分的理由改变某些编程风格, 但我们还是应该遵循一致性原则，尽量不这么做. 本指南的另一个观点是 C++ 特性的臃肿. C++ 是一门包含大量高级特性的庞大语言. 某些情况下, 我 们会限制甚至禁止使用某些特性. 这么做是为了保持代码清爽, 避免这些特性可能导致的各种问题. 指南 中列举了这类特性, 并解释为什么这些特性被限制使用. Google 主导的开源项目均符合本指南的规定. 注意: 本指南并非 C++ 教程, 我们假定读者已经对 C++ 非常熟悉. 2.2 1. 头文件 通常每一个 .cc 文件都有一个对应的 .h 文件. 也有一些常见例外, 如单元测试代码和只包含 main() 函 数的 .cc 文件. 正确使用头文件可令代码在可读性、文件大小和性能上大为改观. 下面的规则将引导你规避使用头文件时的各种陷阱. 2.2.1 1.1. Self-contained 头文件 Tip: 头文件应该能够自给自足（self-contained, 也就是可以作为第一个头文件被引入），以 .h 结尾。至 于用来插入文本的文件，说到底它们并不是头文件，所以应以 .inc 结尾。不允许分离出 -inl.h 头文件 的做法. 所有头文件要能够自给自足。换言之，用户和重构工具不需要为特别场合而包含额外的头文件。详言之， 一个头文件要有1.2. #define 保护，统统包含它所需要的其它头文件，也不要求定义任何特别 symbols. 不过有一个例外，即一个文件并不是 self-contained 的，而是作为文本插入到代码某处。或者，文件内容 实际上是其它头文件的特定平台（platform-specific）扩展部分。这些文件就要用 .inc 文件扩展名。 如果 .h 文件声明了一个模板或内联函数，同时也在该文件加以定义。凡是有用到这些的 .cc 文件，就 得统统包含该头文件，否则程序可能会在构建中链接失败。不要把这些定义放到分离的 -inl.h 文件里 （译者注：过去该规范曾提倡把定义放到 -inl.h 里过）。 2.2. 1. 头文件 5
Google开源项目风格指南有个例外：如果某函数模板为所有相关模板参数显式实例化，或本身就是某类的一个私有成员，那么它就只能定义在实例化该模板的.cc文件里。2.2.21.2.#define保护Tip:所有头文件都应该使用来防止头文件被多重包含，命名格式当是：#define<PROJECT>_<PATH>_<FILE>_H_为保证唯一性，头文件的命名应该基于所在项目源代码树的全路径。例如，项目foo中的头文件foo/src/bar/baz.h可按如下方式保护：#ifndef FOO BAR BAZ H#defineFOO_BAR_BAZ_H#endif //FOO_BAR_BAZ_H2.2.31.3.前置声明Tip：尽可能地避免使用前置声明。使用#include包含需要的头文件即可。定义：所谓「前置声明」（forwarddeclaration）是类、函数和模板的纯粹声明，没伴随着其定义优点：·前置声明能够节省编译时间，多余的#include会迫使编译器展开更多的文件，处理更多的输入。。前置声明能够节省不必要的重新编译的时间。#include使代码因为头文件中无关的改动而被重新编译多次。缺点：。前置声明隐藏了依赖关系，头文件改动时，用户的代码会跳过必要的重新编译过程。前置声明可能会被库的后续更改所破坏。前置声明函数或模板有时会妨碍头文件开发者变动其API.例如扩大形参类型，加个自带默认参数的模板形参等等。。前置声明来自命名空间std：：的symbol时，其行为未定义。。很难判断什么时候该用前置声明，什么时候该用#include。极端情况下，用前置声明代替includes甚至都会暗暗地改变代码的含义：//b.h:structB;structD:BO;(continues on next page)6Chapter2.C++风格指南-内容目录
Google 开源项目风格指南 有个例外：如果某函数模板为所有相关模板参数显式实例化，或本身就是某类的一个私有成员，那么它 就只能定义在实例化该模板的 .cc 文件里。 2.2.2 1.2. #define 保护 Tip: 所有头文件都应该使用 #define 来防止头文件被多重包含, 命名格式当是: <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.2.3 1.3. 前置声明 Tip: 尽可能地避免使用前置声明。使用 #include 包含需要的头文件即可。 定义： 所谓「前置声明」（forward declaration）是类、函数和模板的纯粹声明，没伴随着其定义. 优点： • 前置声明能够节省编译时间，多余的 #include 会迫使编译器展开更多的文件，处理更多的输入。 • 前置声明能够节省不必要的重新编译的时间。#include 使代码因为头文件中无关的改动而被重新 编译多次。 缺点： • 前置声明隐藏了依赖关系，头文件改动时，用户的代码会跳过必要的重新编译过程。 • 前置声明可能会被库的后续更改所破坏。前置声明函数或模板有时会妨碍头文件开发者 变动其 API. 例如扩大形参类型，加个自带默认参数的模板形参等等。 • 前置声明来自命名空间 std:: 的 symbol 时，其行为未定义。 • 很难判断什么时候该用前置声明，什么时候该用 #include 。极端情况下，用前置声明 代替 includes 甚至都会暗暗地改变代码的含义： // b.h: struct B {}; struct D : B {}; (continues on next page) 6 Chapter 2. C++ 风格指南 - 内容目录
Google开源项目风格指南(continued from previous page)//.good_user.cc:#include "b.h"void f(B*);void f(void*);void test(D*x)(f(x);}// callsf(B*)如果#include被B和D的前置声明替代，test（）就会调用f（void*），前置声明了不少来自头文件的symbol时，就会比单单一行的include允长。：仅仅为了能前置声明而重构代码（比如用指针成员代替对象成员）会使代码变得更慢更复杂.结论：·尽量避免前置声明那些定义在其他项目中的实体。·函数：总是使用#include.·类模板：优先使用#include至于什么时候包含头文件，参见1.5.#include的路径及顺序。2.2.41.4.内联函数Tip：只有当函数只有10行甚至更少时才将其定义为内联函数定义：当函数被声明为内联函数之后，编译器会将其内联展开，而不是按通常的函数调用机制进行调用,优点：只要内联的函数体较小，内联该函数可以令目标代码更加高效，对于存取函数以及其它函数体比较短，性能关键的函数，鼓励使用内联，缺点：滥用内联将导致程序变得更慢，内联可能使目标代码量或增或减，这取决于内联函数的大小内联非常短小的存取函数通常会减少代码大小，但内联一个相当大的函数将戏剧性的增加代码大小，现代处理器由于更好的利用了指令缓存，小巧的代码往往执行更快。结论：一个较为合理的经验准则是，不要内联超过10行的函数，谨慎对待析构函数，析构函数往往比其表面看起来要更长，因为有隐含的成员和基类析构函数被调用！另一个实用的经验准则：内联那些包含循环或switch语句的函数常常是得不偿失（除非在大多数情况下，这些循环或switch语句从不被执行)，72.2.1.头文件
Google 开源项目风格指南 (continued from previous page) // 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. 至于什么时候包含头文件，参见1.5. #include 的路径及顺序 。 2.2.4 1.4. 内联函数 Tip: 只有当函数只有 10 行甚至更少时才将其定义为内联函数. 定义: 当函数被声明为内联函数之后, 编译器会将其内联展开, 而不是按通常的函数调用机制进行调 用. 优点: 只要内联的函数体较小, 内联该函数可以令目标代码更加高效. 对于存取函数以及其它函数体 比较短, 性能关键的函数, 鼓励使用内联. 缺点: 滥用内联将导致程序变得更慢. 内联可能使目标代码量或增或减, 这取决于内联函数的大小. 内联非常短小的存取函数通常会减少代码大小, 但内联一个相当大的函数将戏剧性的增加代 码大小. 现代处理器由于更好的利用了指令缓存, 小巧的代码往往执行更快。 结论: 一个较为合理的经验准则是, 不要内联超过 10 行的函数. 谨慎对待析构函数, 析构函数往往 比其表面看起来要更长, 因为有隐含的成员和基类析构函数被调用! 另一个实用的经验准则: 内联那些包含循环或 switch 语句的函数常常是得不偿失 (除非在大 多数情况下, 这些循环或 switch 语句从不被执行). 2.2. 1. 头文件 7