Google 开源项目风格指南.docx
《Google 开源项目风格指南.docx》由会员分享,可在线阅读,更多相关《Google 开源项目风格指南.docx(278页珍藏版)》请在得力文库 - 分享文档赚钱的网站上搜索。
1、Google 开源项目风格指南May 29, 2022Contentsi1 Google 开源项目风格指南中文版12 C+ 风格指南 - 内容目录32.10. 扉页32.21. 头文件52.32. 作用域102.43. 类162.54. 函数242.65. 来自 Google 的奇技282.76. 其他 C+ 特性302.87. 命名约定512.98. 注释562.10 9. 格式632.11 10. 规则特例802.12 11. 结 束语813 Objective-C 风格指南 - 内容目录833.1 Google Objective-C Style Guide 中文版833.2 留白和格式
2、873.3命名913.4注释953.5 Cocoa 和 Objective-C 特性973.6 Cocoa 模式1084 Python 风格指南 - 内容目录1114.1扉页1114.2背景1114.3 Python 语言规范1124.4 Python 风格规范1284.5 临别赠言1525 Shell 风格指南 - 内容目录1535.1扉页1535.2背景1535.3Shell 文件和解释器调用1545.4环境1555.5注释1555.6格式1575.7 特性及错误1625.8 命名约定1675.9 调用命令1705.10 结论1716 Javascript 风格指南 - 内容目录1736.
3、1背景1736.2 Javascript 语言规范1736.3 Javascript 风格规范1847 TypeScript 风格指南2277.1前言2277.2 语法规范2287.3 语言特性2347.4 代码管理2557.5 类型系统2617.6一致性271CHAPTER 1Google 开源项目风格指南中文版 ReadTheDocs 托管地址:在线阅读最新版本 GitHub 托管地址:zh-google-styleguide 离线文档下载地址:releaseNote: 声 明本项目并非 Google 官方项目,而是由国内程序员凭热情创建和维护。如果你关注的是 Google 官方英文版,请
4、移步 Google Style Guide 。每个较大的开源项目都有自己的风格指南:关于如何为该项目编写代码的一系列约定(有时候会比较武断)。当所有代码均保持一致的风格,在理解大型代码库时更为轻松。“风格”的含义涵盖范围广,从“变量使用驼峰格式(camelCase)”到“决不使用全局变量”再到“决不使用异常”,等等诸如此类。英文版项目维护的是在 Google 使用的编程风格指南。如果你正在修改的项目源自 Google,你可能会被引导至英文版项目页面,以了解项目所使用的风格。我们已经发布了七份 中文版的风格指南:1. Google C+ 风格指南2. Google Objective-C 风格指
5、南3. Google Python 风格指南4. Google JavaScript 风格指南5. Google Shell 风格指南16. Google JSON 风格指南7. Google TypeScript 风格指南中文版项目采用 reStructuredText 纯文本标记语法,并使用 Sphinx 生成 HTML / CHM / PDF 等文档格式。 英文版项目还包含 cpplint 一个用来帮助适应风格准则的工具,以及 google-c-style.el,Google风格的 Emacs 配置文件。 另外,招募志愿者翻译 JavaScript Style Guide 以及 XML
6、Document Format Style Guide ,有意者请联系 Yang.Y 。CHAPTER 2C+ 风格指南 - 内容目录Contents C+ 风格指南 - 内容目录2.1 0. 扉 页版 本 4.45原作者Benjy Weinberger Craig Silverstein Gregory Eitzmann Mark Mentovai Tashana Landray翻译YuleFox Yang.Y acgtyrant lilinsanity项目主页 Google Style Guide3 Google 开源项目风格指南 - 中文版2.1.1 0.1 译者前言Google 经常会
7、发布一些开源项目, 意味着会接受来自其他代码贡献者的代码. 但是如果代码贡献者的编程风格与 Google 的不一致, 会给代码阅读者和其他代码提交者造成不小的困扰. Google 因此发布了这份自己的编程风格指南, 使所有提交代码的人都能获知 Google 的编程风格.翻译初衷:规则的作用就是避免混乱. 但规则本身一定要权威, 有说服力, 并且是理性的. 我们所见过的大部分编程规范, 其内容或不够严谨, 或阐述过于简单, 或带有一定的武断性.Google 保持其一贯的严谨精神, 5 万汉字的指南涉及广泛, 论证严密. 我们翻译该系列指南的主因也正是其严谨性. 严谨意味着指南的价值不仅仅局限于它
8、罗列出的规范, 更具参考意义的是它为了列出规范而做的谨慎权衡过程.指南不仅列出你要怎么做, 还告诉你为什么要这么做, 哪些情况下可以不这么做, 以及如何权衡其利弊. 其他团队未必要完全遵照指南亦步亦趋, 如前面所说, 这份指南是 Google 根据自身实际情况打造的, 适用于其主导的开源项目. 其他团队可以参照该指南, 或从中汲取灵感, 建立适合自身实际情况的规范.我们在翻译的过程中, 收获颇多. 希望本系列指南中文版对你同样能有所帮助.我们翻译时也是尽力保持严谨, 但水平所限, bug 在所难免. 有任何意见或建议, 可与我们取得联系. 中文版和英文版一样, 使用 Artistic Lice
9、nse/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
10、中文社区众帮了译者不少忙,谢谢他们。因为 C+ Primer 尚未完全入门,暂时没有翻译类章节和其它一些小章节。 2009-06 3.133 : YuleFox 的 1.0 版已经相当完善, 但原版在近一年的时间里, 其规范也发生了一些变化.Yang.Y 与 YuleFox 一拍即合, 以项目的形式来延续中文版: Google 开源项目风格指南 -中文版项目.主要变化是同步到 3.133 最新英文版本, 做部分勘误和改善可读性方面的修改, 并改进排版效果. Yang.Y 重新翻修, YuleFox 做后续评审. 2008-07 1.0 : 出自 YuleFox 的 Blog, 很多地方摘录的也
11、是该版本.Google 开源项目风格指南2.1.2 0.2 背 景C+ 是 Google 大部分开源项目的主要编程语言. 正如每个 C+ 程序员都知道的, C+ 有很多强大的特性, 但这种强大不可避免的导致它走向复杂,使代码更容易产生 bug, 难以阅读和维护.本指南的目的是通过详细阐述 C+ 注意事项来驾驭其复杂性. 这些规则在保证代码易于管理的同时, 也能高效使用 C+ 的语言特性.风格, 亦被称作可读性, 也就是指导 C+ 编程的约定. 使用术语“风格”有些用词不当, 因为这些习惯远不止源代码文件格式化这么简单.使代码易于管理的方法之一是加强代码一致性. 让任何程序员都可以快速读懂你的代
12、码这点非常重要. 保持统一编程风格并遵守约定意味着可以很容易根据“模式匹配”规则来推断各种标识符的含义. 创建通用, 必需的习惯用语和模式可以使代码更容易理解. 在一些情况下可能有充分的理由改变某些编程风格, 但我们还是应该遵循一致性原则,尽量不这么做.本指南的另一个观点是 C+ 特性的臃肿. C+ 是一门包含大量高级特性的庞大语言. 某些情况下, 我们会限制甚至禁止使用某些特性. 这么做是为了保持代码清爽, 避免这些特性可能导致的各种问题. 指南中列举了这类特性, 并解释为什么这些特性被限制使用.Google 主导的开源项目均符合本指南的规定.注意: 本指南并非 C+ 教程, 我们假定读者已
13、经对 C+ 非常熟悉.2.2 1. 头文件通常每一个 .cc 文件都有一个对应的 .h 文件. 也有一些常见例外, 如单元测试代码和只包含 main() 函数的 .cc 文件.正确使用头文件可令代码在可读性、文件大小和性能上大为改观. 下面的规则将引导你规避使用头文件时的各种陷阱.2.2.1 1.1. Self-contained 头文件Tip: 头文件应该能够自给自足(self-contained, 也就是可以作为第一个头文件被引入),以 .h 结尾。至于用来插入文本的文件,说到底它们并不是头文件,所以应以 .inc 结尾。不允许分离出 -inl.h 头文件的做法.所有头文件要能够自给自足。
14、换言之,用户和重构工具不需要为特别场合而包含额外的头文件。详言之, 一个头文件要有1.2. #define 保护,统统包含它所需要的其它头文件,也不要求定义任何特别 symbols.不过有一个例外,即一个文件并不是 self-contained 的,而是作为文本插入到代码某处。或者,文件内容实际上是其它头文件的特定平台(platform-specific)扩展部分。这些文件就要用 .inc 文件扩展名。如果 .h 文件声明了一个模板或内联函数,同时也在该文件加以定义。凡是有用到这些的 .cc 文件,就得统统包含该头文件,否则程序可能会在构建中链接失败。不要把这些定义放到分离的 -inl.h 文
15、件里(译者注:过去该规范曾提倡把定义放到 -inl.h 里过)。2.2. 1. 头 文 件9有个例外:如果某函数模板为所有相关模板参数显式实例化,或本身就是某类的一个私有成员,那么它就只能定义在实例化该模板的 .cc 文件里。2.2.2 1.2. #define 保 护Tip:所有头文件都应该有#define保护来防止头文件被多重包含,命名格式当是:_H_ .为保证唯一性, 头文件的命名应该基于所在项目源代码树的全路径. 例如, 项目 foo 中的头文件 foo/ src/bar/baz.h 可按如下方式保护:#ifndef FOO_BAR_BAZ_H_ #define FOO_BAR_BAZ
16、_H_.#endif / FOO_BAR_BAZ_H_2.2.3 1.3. 前置声明Tip: 尽可能地避免使用前置声明。使用 #include 包含需要的头文件即可。定义:所谓前置声明(forward declaration)是类、函数和模板的纯粹声明,没伴随着其定义.优点: 前置声明能够节省编译时间,多余的 #include 会迫使编译器展开更多的文件,处理更多的输入。 前置声明能够节省不必要的重新编译的时间。#include 使代码因为头文件中无关的改动而被重新编译多次。缺点: 前置声明隐藏了依赖关系,头文件改动时,用户的代码会跳过必要的重新编译过程。 前置声明可能会被库的后续更改所破坏。
17、前置声明函数或模板有时会妨碍头文件开发者 变动其 API. 例如扩大形参类型,加个自带默认参数的模板形参等等。 前置声明来自命名空间 std: 的 symbol 时,其行为未定义。 很难判断什么时候该用前置声明,什么时候该用 #include 。极端情况下,用前置声明代替 #include 甚至都会暗暗地改变代码的含义:/ b.h:struct B ;struct D : B ;(continues on next page)(continued from previous page)/ good_user.cc:#include b.h void f(B*); void f(void*);v
18、oid 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
19、 行甚至更少时才将其定义为内联函数.定义:优点:缺点:结论:当函数被声明为内联函数之后, 编译器会将其内联展开, 而不是按通常的函数调用机制进行调用.只要内联的函数体较小, 内联该函数可以令目标代码更加高效. 对于存取函数以及其它函数体比较短, 性能关键的函数, 鼓励使用内联.滥用内联将导致程序变得更慢. 内联可能使目标代码量或增或减, 这取决于内联函数的大小. 内联非常短小的存取函数通常会减少代码大小, 但内联一个相当大的函数将戏剧性的增加代码大小. 现代处理器由于更好的利用了指令缓存, 小巧的代码往往执行更快。一个较为合理的经验准则是, 不要内联超过 10 行的函数. 谨慎对待析构函数,
20、析构函数往往比其表面看起来要更长, 因为有隐含的成员和基类析构函数被调用!另一个实用的经验准则: 内联那些包含循环或 switch 语句的函数常常是得不偿失 (除非在大多数情况下, 这些循环或 switch 语句从不被执行).有些函数即使声明为内联的也不一定会被编译器内联, 这点很重要; 比如虚函数和递归函数就不会被正常内联. 通常, 递归函数不应该声明成内联函数.(YuleFox 注: 递归调用堆栈的展开并不像循环那么简单, 比如递归层数在编译时可能是未知的, 大多数编译器都不支持内联递归函数). 虚函数内联的主要原因则是想把它的函数体放在类定义内, 为了图个方便, 抑或是当作文档描述其行为
21、, 比如精短的存取函数.2.2.5 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
22、.h 的功能, foo.cc 中包含头文件的次序如下:1. dir2/foo2.h (优先位置, 详情如下)2. C 系统文件3. C+ 系统文件4. 其他库的 .h 文件5. 本项目内 .h 文件这种优先的顺序排序保证当 dir2/foo2.h 遗漏某些必要的库时,dir/foo.cc 或 dir/foo_test.cc 的构建会立刻中止。因此这一条规则保证维护这些文件的人们首先看到构建中止的消息而不是维护其他包的人们。dir/foo.cc 和 dir2/foo2.h 通常位于同一目录下 (如 base/basictypes_unittest.cc 和 base/ basictypes.h)
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- Google 开源项目风格指南 项目 风格 指南
限制150内