Google开源项目风格指南：中文版与编程约定

需积分: 0 155 浏览量更新于2024-07-17 收藏 2.1MB PDF 举报

"Google开源项目风格指南是一个由国内程序员根据Google官方编程风格编写的中文版指导文档，旨在为参与开源项目的开发者提供一套统一的编码规范和最佳实践。该指南不仅包含了Google在C++, Objective-C, Python, JSON, 和Shell编程语言中的具体风格建议，如变量命名规则（驼峰式命名法）、避免全局变量的使用以及对异常处理的指导，它还强调了代码一致性的重要性，这对于理解和协作维护大型代码库至关重要。每一部分的中文风格指南都遵循reStructuredText纯文本标记语法，利用Sphinx工具将文档转换成HTML、CHM或PDF格式，方便不同平台的阅读。此外，英文版的项目除了风格指南本身，还提供了额外的辅助工具，如cpplint来检查代码是否符合风格准则，以及google-c-style.el这样的Emacs配置文件，以支持开发者在开发过程中快速适应Google的编程风格。值得注意的是，虽然这个中文项目并非Google官方出品，但其目标是尽可能地贴近Google内部的标准，并且鼓励志愿者参与到翻译其他如JavaScript和XML文档格式的风格指南工作中，有兴趣的开发者可以联系项目负责人Yang.Y. 通过这份详细的指南，无论是Google开源项目的新参与者还是经验丰富的开发者，都能从中找到提高代码质量和团队协作效率的宝贵资源。"

2019/1/7 Google 开源项目风格指南

file:///C:/Users/YQ05/Downloads/zh-google-styleguide/zh-google-styleguide-latest/contents.html#document-google-shell-styleguide/contents 16/166

 Tip

禁止定义静态储存周期非POD变量，禁止使用含有副作用的函数初始化POD全局变量，因

为多编译单元中的静态变量执行时的构造和析构顺序是未明确的，这将导致代码的不可移

植。

禁止使用类的静态储存周期变量：由于构造和析构函数调用顺序的不确定性，它们会导致难

以发现的 bug 。不过 constexpr 变量除外，毕竟它们又不涉及动态初始化或析构。

静态生存周期的对象，即包括了全局变量，静态变量，静态类成员变量和函数静态变量，都

必须是原生数据类型 (POD : Plain Old Data): 即 int, char 和 ﬂoat, 以及 POD 类型的指针、数

组和结构体。

静态变量的构造函数、析构函数和初始化的顺序在 C++ 中是只有部分明确的，甚至随着构建

变化而变化，导致难以发现的 bug. 所以除了禁用类类型的全局变量，我们也不允许用函数返

回值来初始化 POD 变量，除非该函数（比如 getenv() 或 getpid() ）不涉及任何全局变量。

函数作用域里的静态变量除外，毕竟它的初始化顺序是有明确定义的，而且只会在指令执行

到它的声明那里才会发生。

 Note

Xris 译注:

同一个编译单元内是明确的，静态初始化优先于动态初始化，初始化顺序按照声明顺序进

行，销毁则逆序。不同的编译单元之间初始化和销毁顺序属于未明确行为 (unspeciﬁed

behaviour)。

同理，全局和静态变量在程序中断时会被析构，无论所谓中断是从 main() 返回还是对

exit() 的调用。析构顺序正好与构造函数调用的顺序相反。但既然构造顺序未定义，那么析

构顺序当然也就不定了。比如，在程序结束时某静态变量已经被析构了，但代码还在跑——比

如其它线程——并试图访问它且失败；再比如，一个静态 string 变量也许会在一个引用了前者

的其它变量析构之前被析构掉。

改善以上析构问题的办法之一是用 quick_exit() 来代替 exit() 并中断程序。它们的不同之

处是前者不会执行任何析构，也不会执行 atexit() 所绑定的任何 handlers. 如果您想在执行

quick_exit() 来中断时执行某 handler（比如刷新 log），您可以把它绑定到

_at_quick_exit() . 如果您想在 exit() 和 quick_exit() 都用上该 handler, 都绑定上去。

综上所述，我们只允许 POD 类型的静态变量，即完全禁用 vector (使用 C 数组替代) 和

string (使用 const char [] )。

如果您确实需要一个 class 类型的静态或全局变量，可以考虑在 main() 函数或

pthread_once() 内初始化一个指针且永不回收。注意只能用 raw 指针，别用智能指针，毕竟

后者的析构函数涉及到上文指出的不定顺序问题。

2019/1/7 Google 开源项目风格指南

file:///C:/Users/YQ05/Downloads/zh-google-styleguide/zh-google-styleguide-latest/contents.html#document-google-shell-styleguide/contents 18/166

经过构造函数完全初始化后的对象可以为 const 类型, 也能更方便地被标准容器或算法使

用.

缺点

如果在构造函数内调用了自身的虚函数, 这类调用是不会重定向到子类的虚函数实现. 即使

当前没有子类化实现, 将来仍是隐患.

在没有使程序崩溃 (因为并不是一个始终合适的方法) 或者使用异常 (因为已经被禁用了)

等方法的条件下, 构造函数很难上报错误

如果执行失败, 会得到一个初始化失败的对象, 这个对象有可能进入不正常的状态, 必须使

用 bool IsValid() 或类似这样的机制才能检查出来, 然而这是一个十分容易被疏忽的方法.

构造函数的地址是无法被取得的, 因此, 举例来说, 由构造函数完成的工作是无法以简单的

方式交给其他线程的.

结论

构造函数不允许调用虚函数. 如果代码允许, 直接终止程序是一个合适的处理错误的方式. 否则,

考虑用 Init() 方法或工厂函数.

构造函数不得调用虚函数, 或尝试报告一个非致命错误. 如果对象需要进行有意义的 (non-

trivial) 初始化, 考虑使用明确的 Init() 方法或使用工厂模式. Avoid Init() methods on objects

with no other states that aﬀect which public methods may be called (此类形式的半构造对象

有时无法正确工作).

3.2. 隐式类型转换

总述

不要定义隐式类型转换. 对于转换运算符和单参数构造函数, 请使用 explicit 关键字.

定义

隐式类型转换允许一个某种类型 (称作

源

类

型

) 的对象被用于需要另一种类型 (称作

目的类

型

)

的位置, 例如, 将一个 int 类型的参数传递给需要 double 类型的函数.

除了语言所定义的隐式类型转换, 用户还可以通过在类定义中添加合适的成员定义自己需要的

转换. 在源类型中定义隐式类型转换, 可以通过目的类型名的类型转换运算符实现 (例如

operator bool() ). 在目的类型中定义隐式类型转换, 则通过以源类型作为其唯一参数 (或唯一无

默认值的参数) 的构造函数实现.

explicit 关键字可以用于构造函数或 (在 C++11 引入) 类型转换运算符, 以保证只有当目的类

型在调用点被显式写明时才能进行类型转换, 例如使用 cast . 这不仅作用于隐式类型转换, 还

能作用于 C++11 的列表初始化语法:

2019/1/7 Google 开源项目风格指南

file:///C:/Users/YQ05/Downloads/zh-google-styleguide/zh-google-styleguide-latest/contents.html#document-google-shell-styleguide/contents 19/166

class Foo {

explicit Foo(int x, double y);

...

};

void Func(Foo f);

此时下面的代码是不允许的:

Func({42, 3.14}); // Error

这一代码从技术上说并非隐式类型转换, 但是语言标准认为这是 explicit 应当限制的行为.

优点

有时目的类型名是一目了然的, 通过避免显式地写出类型名, 隐式类型转换可以让一个类型

的可用性和表达性更强.

隐式类型转换可以简单地取代函数重载.

在初始化对象时, 列表初始化语法是一种简洁明了的写法.

缺点

隐式类型转换会隐藏类型不匹配的错误. 有时, 目的类型并不符合用户的期望, 甚至用户根

本没有意识到发生了类型转换.

隐式类型转换会让代码难以阅读, 尤其是在有函数重载的时候, 因为这时很难判断到底是哪

个函数被调用.

单参数构造函数有可能会被无意地用作隐式类型转换.

如果单参数构造函数没有加上 explicit 关键字, 读者无法判断这一函数究竟是要作为隐式

类型转换, 还是作者忘了加上 explicit 标记.

并没有明确的方法用来判断哪个类应该提供类型转换, 这会使得代码变得含糊不清.

如果目的类型是隐式指定的, 那么列表初始化会出现和隐式类型转换一样的问题, 尤其是在

列表中只有一个元素的时候.

结论

在类型定义中, 类型转换运算符和单参数构造函数都应当用 explicit 进行标记. 一个例外是,

拷贝和移动构造函数不应当被标记为 explicit , 因为它们并不执行类型转换. 对于设计目的就

是用于对其他类型进行透明包装的类来说, 隐式类型转换有时是必要且合适的. 这时应当联系

项目组长并说明特殊情况.

不能以一个参数进行调用的构造函数不应当加上 explicit . 接受一个 std::initializer_list 作

为参数的构造函数也应当省略 explicit , 以便支持拷贝初始化 (例如 MyType m = {1, 2};) .

2019/1/7 Google 开源项目风格指南

file:///C:/Users/YQ05/Downloads/zh-google-styleguide/zh-google-styleguide-latest/contents.html#document-google-shell-styleguide/contents 20/166

3.3. 可拷贝类型和可移动类型

总述

如果你的类型需要, 就让它们支持拷贝 / 移动. 否则, 就把隐式产生的拷贝和移动函数禁用.

定义

可拷贝类型允许对象在初始化时得到来自相同类型的另一对象的值, 或在赋值时被赋予相同类

型的另一对象的值, 同时不改变源对象的值. 对于用户定义的类型, 拷贝操作一般通过拷贝构造

函数与拷贝赋值操作符定义. string 类型就是一个可拷贝类型的例子.

可移动类型允许对象在初始化时得到来自相同类型的临时对象的值, 或在赋值时被赋予相同类

型的临时对象的值 (因此所有可拷贝对象也是可移动的). std::unique_ptr<int> 就是一个可移动

但不可复制的对象的例子. 对于用户定义的类型, 移动操作一般是通过移动构造函数和移动赋

值操作符实现的.

拷贝 / 移动构造函数在某些情况下会被编译器隐式调用. 例如, 通过传值的方式传递对象.

优点

可移动及可拷贝类型的对象可以通过传值的方式进行传递或者返回, 这使得 API 更简单, 更安

全也更通用. 与传指针和引用不同, 这样的传递不会造成所有权, 生命周期, 可变性等方面的混

乱, 也就没必要在协议中予以明确. 这同时也防止了客户端与实现在非作用域内的交互, 使得它

们更容易被理解与维护. 这样的对象可以和需要传值操作的通用 API 一起使用, 例如大多数容

器.

拷贝 / 移动构造函数与赋值操作一般来说要比它们的各种替代方案, 比如 Clone() , CopyFrom()

or Swap() , 更容易定义, 因为它们能通过编译器产生, 无论是隐式的还是通过 = default . 这种

方式很简洁, 也保证所有数据成员都会被复制. 拷贝与移动构造函数一般也更高效, 因为它们不

需要堆的分配或者是单独的初始化和赋值步骤, 同时, 对于类似省略不必要的拷贝这样的优化

它们也更加合适.

移动操作允许隐式且高效地将源数据转移出右值对象. 这有时能让代码风格更加清晰.

缺点

许多类型都不需要拷贝, 为它们提供拷贝操作会让人迷惑, 也显得荒谬而不合理. 单件类型

( Registerer ), 与特定的作用域相关的类型 ( Cleanup ), 与其他对象实体紧耦合的类型 ( Mutex ) 从

逻辑上来说都不应该提供拷贝操作. 为基类提供拷贝 / 赋值操作是有害的, 因为在使用它们时

会造成对象切割 . 默认的或者随意的拷贝操作实现可能是不正确的, 这往往导致令人困惑并且

难以诊断出的错误.

剩余165页未读，继续阅读

sheelheart

粉丝: 0
资源: 5

Google开源项目风格指南：中文版与编程约定

Google 开源项目风格指南_中文版

Python-Google开源项目风格指南中文版

谷歌开源项目风格指南

谷歌开源项目风格指南.rar

Google 开源项目风格指南.pdf

Google 开源项目风格指南 扫描版

Python风格规范 — Google 开源项目风格指南.pdf

A-2017-Google 开源项目风格指南

Google 开源项目风格指南-C++. 20150928

Google开源项目风格指南（中文版）

最新资源

Google 开源项目风格指南扫描版