Google C++代码规范笔记（一）

C++规范原文：http://google.github.io/styleguide/cppguide.html
参考翻译：https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/

C++版本的限定

目前本规范对标C++11，因此不应使用C++14和C++17的特性。
编码时应该避免使用最新C++版本（目前为C++17）已移除的特性，以及会导致代码在最新C++版本中出现不同含义的特性。
一些C++特性在本规范中会被限制使用或被禁止使用。
不要使用非标准C++特性（在non-standard extensions一章说明）。

头文件（Header Files）

如果 .h 文件声明了一个模板或内联函数，同时也在该文件加以定义。
至于用来插入文本的文件，说到底它们并不是头文件，所以应以 .inc 结尾。（不允许分离出 -inl.h 头文件的做法）

如果一个文件并不是 self-contained 的，而是作为文本插入到代码某处。或者，文件内容实际上是其它头文件的特定平台（platform-specific）扩展部分。这些文件就要用 .inc 文件扩展名。

模板和内联函数的定义和声明应该放在同一个.h文件里。如果声明和定义分开在不同文件，在.cc使用的时候要全部include进来。
有个例外：如果某函数模板为所有相关模板参数显式实例化，或本身就是某类的一个私有成员，那么允许将其定义在（且只能定义在）实例化该模板的 .cc 文件里。

头文件保护：名字格式:

<PROJECT>_<PATH>_<FILE>_H_

为保证唯一性，应该使用全路径，例如foo/src/bar/baz.h：

#ifndef FOO_BAR_BAZ_H_
#define FOO_BAR_BAZ_H_
...
#endif  // FOO_BAR_BAZ_H_

前置声明：
尽可能地避免使用前置声明（类、函数或模板）。使用 #include 包含需要的头文件即可。

前置声明的好处：可以节省编译时间（要读.h文件）以及不必要的重新编译（.h文件有修改就要重新编译.cc，即使修改和这个.cc不相关）。

内联函数：
只有当函数只有很少代码（例如10 行甚至更少）时才将其定义为内联函数（例如存取函数，或性能关键的函数）。
析构不要内联，析构函数往往比其表面看起来要更长, 因为有隐含的成员和基类析构函数被调用！（现代处理器由于更好的利用了指令缓存, 小巧的代码往往执行更快。）
包含循环或 switch 语句的函数不要内联（除非在大多数情况下, 这些循环或 switch 语句不会被执行）。
有些函数即使声明为内联的也不一定会被编译器内联, 这点很重要; 比如虚函数和递归函数就不会被正常内联。通常, 递归函数不应该声明成内联函数。虚函数内联的主要原因则是想把它的函数体放在类定义内, 或为了图方便, 抑或是当作文档描述其行为, 比如精短的存取函数。

包含头文件：
include头文件的顺序：本文件相关头文件, C库, C++库, 其他库的.h, 本项目内的.h。
例如对于dir/foo.cc，它要包含自己的头文件dir2/foo2.h，则顺序为:

1. dir2/foo2.h.
2. 隔一个空行
3. C system files.
4. C++ system files.
5. 隔一个空行
6. Other libraries’ .h files.
7. Your project’s .h files.

而每一部分的多个头文件按照字母表顺序排列，（对于旧的代码不按字母表顺序的，也要抽时间改正）。
如果有条件编译的，例如下例，隔一个空行放于其后，

#ifdef LANG_CXX11
#include 
#endif  // LANG_CXX11

项目内的头文件应按照项目源代码目录树结构排列，例如对于 my-project/src/base/logging.h ，包含它应该写成：

#include "base/logging.h"

您所依赖的符号 (symbols) 被哪些头文件所定义，您就应该包含（include）哪些头文件。比如您要用到 bar.h 中的某个符号, 哪怕您所包含的 foo.h 已经包含了 bar.h, 也照样得包含 bar.h, 除非 foo.h 有明确说明它会自动向您提供 bar.h 中的 symbol。

作用域（scoping）

命名空间：
命名空间将全局作用域细分为独立的、具名的作用域, 可有效防止全局作用域的命名冲突. （例如project1::Foo和project2::Foo就是两个不同的symbols，当然在每个namespace内部可以直接使用Foo而无需加前缀）。

除了极少情况之外，我们都要将代码放到命名空间里。命名空间应该根据project name或path来唯一命名。
禁止使用 using 指示（using-directive），如using namespace foo。
禁止使用内联命名空间（inline namespace）。因为内联命名空间会自动把内部的标识符放到外层作用域，具有迷惑性。内联命名空间主要用于ABI不同版本的兼容性。

namespace的书写建议：
1. namespace的末尾要加注释。（如下例，表明namespace范围结束。）
2. namespace把一个源文件中 includes、gflags、其他命名空间的类的前置声明 后面的代码都包进来。

#include "a.h"

DEFINE_FLAG(bool, someflag, false, "dummy flag");

namespace a {

...code for a...    // 左对齐

} // namespace a

3.To place generated protocol message code in a namespace, use the package specifier in the .proto file。
4. 不要在命名空间std内声明任何东西, 包括标准库的类前置声明。在std命名空间声明实体是未定义的行为，会导致如不可移植的问题。声明标准库下的实体时需要包含对应的头文件。
5. 不应该使用 using 指示 引入整个命名空间的标识符号：

// 禁止 —— 污染命名空间
using namespace foo;

6.不要在头文件中的命名空间作用域内使用命名空间别名，除非这个命名空间（指前者）明确的标记为只有内部使用。因为在头文件中，任何被import进命名空间的东西都会被认为是该头文件提供的public API。举例，下面三种写法都是可以的：

//在.cc文件中定义一个简短的别名，来简化对一个常用名字的使用。
namespace baz = ::foo::bar::baz;

//在.h文件中定义一个简短的别名
//(注意，这里明确注释了，impl是内部namespace，因此可以在其中定义别名；
// 另外，在内联函数中定义别名是OK的，因为只在函数范围有效。)
namespace librarian {
namespace impl {  // Internal, not part of the API.
namespace sidetable = ::pipeline_diagnostics::sidetable;
}  // namespace impl

inline void my_inline_function() {
  // namespace alias local to a function (or method).
  namespace baz = ::foo::bar::baz;
  ...
}
}  // namespace librarian

当一个（类、函数、变量）定义在.cc文件内，且不会被外部使用，则把它们放进一个匿名命名空间或（对于函数和变量）声明为static，这叫做internal linkage。但是不要在.h文件中用匿名命名空间和static！
匿名命名空间的写法：

namespace {
...
}  // namespace

我们极罕见会使用完全裸的全局函数，而是倾向于把非成员函数放到一个命名空间中。
不要只是为了把一系列静态函数放在一起而定义一个类，这样做和给一系列函数命名时加一个相同前缀一样是没什么卵用的，类的静态成员函数应该是和类的实例或类的静态数据有紧密关联的。
如果你要定义一个跟类的实例没啥关系的函数，则可以把它定义为非成员函数或类的static成员。非成员函数应该不依赖外部变量，并且应该总是放在一个命名空间里。如果这个非成员函数只在当前.cc里使用，就用internal linkage限制一下作用域。

C++允许在函数的任何地方声明变量。提倡在尽可能小的作用域中声明变量, 离第一次使用越近越好. 这使得代码浏览者更容易定位变量声明的位置, 了解变量的类型和初始值。 特别是，应使用初始化的方式替代声明再赋值：

int i;
i = f(); // 坏——初始化和声明分离
int j = g(); // 好——初始化时声明
std::vector<int> v;
v.push_back(1);  //倾向于用小括号来初始化
v.push_back(2);
vector<int> v = {1, 2}; // 好——v 一开始就初始化

属于 if, while 和 for 语句的变量应当在这些语句里面声明，这样子这些变量的作用域就被限制在这些语句中了。
有一个例外, 如果变量是一个对象, 每次进入作用域都要调用其构造函数, 每次退出作用域都要调用其析构函数. 这会导致效率降低。这样就最好在循环外声明。

静态和全局变量：
禁止定义有静态存储期的对象，除非这个对象是 trivially destructible 的。trivially destructible的对象是指其析构函数（包括基类的析构和成员的析构）不做任何事情，正式一点的解释就是，这个对象的类没有用户自定义的析构或虚析构，并且其所有的基类和非静态成员也都是trivially destructible的。
函数里定义的局部静态变量可以进行动态初始化。而不建议对类的静态成员变量或命名空间作用域的变量进行动态初始化（少数情况除外）。
根据经验，一个可以用constexpr声明的全局变量就满足这些要求。？？？？

任何对象都有它的存储期，这与它的生命周期有关。具有静态存储期的对象的生存周期是从初始化完成到程序结束，例如，命名空间变量（即全局变量）、类的静态数据成员以及函数内的static局部变量是一样的。
但是，函数的static局部变量是在代码第一次执行到的时候才被初始化，另外几个是在程序启动时就初始化了。而所有静态存储期对象都会在程序退出时被销毁。

动态初始化是指，在初始化过程中会有non-trival的东西（例如在构造函数中分配内存，又例如一个变量需要根据当前进程pid做初始化）。
静态初始化是对于具有静态存储期的对象来说的（例如将对象初始化为一个给定常亮或全0）。当然，一个对象在动态初始化前可以先做个静态初始化，所以他俩并不是完全对立的。

全局和静态变量在一些场景下是非常有用的，但是如果他们有动态初始化或non-trival的析构，就会增加复杂度且容易产生难以定位的bug。因为不同编译单元（即不同.o）之间，初始化的顺序是不确定的，析构的顺序当然也是不确定的（因为析构总是初始化的反序这点是固定的）。所以如果有两个静态存储期变量之间有依赖，就有可能出现一个变量的生存期还没开始就被使用了，或者使用了已经结束生命的变量。再比如，一个进程起了多个线程，由于静态存储期对象的销毁是在before unjoined threads are terminated，那就可能出现其他线程试图访问已退出的线程里的对象。
问：这里的joined at exit是什么意思？？

因此我们只允许trivially destructible的静态存储期对象，例如，对于类的对象，析构函数必须是trival的（初始化下面另讲）。基础类型（例如指针和int以及他们的array）以及被标记为constexpr的变量也是OK的。下面是几个例子：

const int kNum = 10;  // allowed

struct X { int n; };
const X kX[] = {{1}, {2}, {3}};  // allowed

void foo() {
  static const char* const kMessages[] = {"hello", "world"};  // allowed
}

// allowed: constexpr guarantees trivial destructor
constexpr std::array<int, 3> kArray = {{1, 2, 3}};

// bad: non-trivial destructor
const string kFoo = "foo";

// bad for the same reason, even though kBar is a reference (the
// rule also applies to lifetime-extended temporary objects)
const string& kBar = StrCat("a", "b", "c");

void bar() {
  // bad: non-trivial destructor
  static std::map<int, int> kData = {{1, 0}, {2, 0}, {3, 0}};
}

这里需要注意一点，引用（如上面的kBar）不是对象，因此不用受destructibility的限制，但仍受动态初始化的限制。特别地，函数里的static引用，static T& t = *new T;，这样写是可以的。

初始化要复杂一些，我们不仅要考虑类的构造函数执行的时机，还要考虑赋值进行初始化的情况：

int n = 5;    // fine
int m = f();  // ? (depends on f)
Foo x;        // ? (depends on Foo::Foo)
Bar y = g();  // ? (depends on g and on Bar::Bar)

只有第一个没有初始化顺序不确定的问题。

这里就要引入一个概念，constant initialization，意思是说，赋值表达式是一个常量表达式，如果需要调构造函数，那么构造函数必须是constexpr修饰的（ABSL_CONST_INIT属性也可以）。

struct Foo { constexpr Foo(int) {} };

int n = 5;  // fine, 5 is a constant expression
Foo x(2);   // fine, 2 is a constant expression and the chosen constructor is constexpr
Foo a[] = { Foo(1), Foo(2), Foo(3) };  // fine

下面的都是有问题的初始化：

// Some declarations used below.
time_t time(time_t*);      // not constexpr!
int f();                   // not constexpr!
struct Bar { Bar() {} };

// Problematic initializations.
time_t m = time(nullptr);  // initializing expression not a constant expression
Foo y(f());                // ditto
Bar b;                     // chosen constructor Bar::Bar() not constexpr

非局部变量的动态初始化是不鼓励的，并且一般是被禁止的。不过如果你确定你的程序里不存在上面说的依赖关系（一个初始化依赖其他初始化），那初始化的顺序就是无关紧要的，这种情况就是允许的，例如：

int p = getpid();  // allowed, as long as no other static variable
                   // uses p in its own initialization

局部的静态变量是可以动态初始化的，这也比较常见。

常见模式的建议：
1.全局字符串：如果你需要一个全局或静态的字符串常量，考虑使用一个字符数组或一个char指针指向一个字符串字面量，字符串字面量已经是静态存储期的了并且更高效。
2.maps、sets和其他动态容器：不允许定义标准库里的动态容器的静态变量，因为他们的析构是non-trival的。你可以考虑使用trival类型的数组，例如用一个int数组的数组（类似map的int,int）或一个int和const char*的键值对的数组来模拟，查找时可以线性查找或排个序然后二分查找。如果你非要用标准库里的动态容器，可以考虑定义成函数范围的static指针。
3.智能指针（unique_ptr, shared_ptr）：智能指针在销毁时会执行一些清理操作，因此也是被禁止的。可以考虑换成这里讲的其他模式建议。一个简单的就解决方案就是，用一个普通指针指向一个动态分配的对象，并且永远不释放。
4.自定义类型的static变量：如果你需要定义一个自定义类型的static常数据，那么，这个自定义类型的destructor必须是trival的，constructor必须是constexpr的。
5.如果上面的建议都行不通，你可以动态地创建对象然后永远不释放它：通过把这个对象的指针绑定到一个函数范围的static指针变量，static const auto* const impl = new T(args…);（如果初始化比较复杂，可以将其放进一个函数或lambda表达式中）。

thread_local变量：
相比其他方式，优先使用thread_local来定义线程局部数据。在函数外部声明的thread_local变量必须初始化为一个真正编译时期的常量（使用ABSL_CONST_INIT属性来保证）。

从C++11开始，变量声明可以用thread_local来标识：

thread_local Foo foo = ...;

这个变量实际上是一组对象的集合，这样一来，在不同线程中访问它，则实际访问的是不同的对象。thread_local变量在很多方面很像静态存储期变量，例如可以在命名空间作用域内、函数内部声明，或作为类的静态成员，但不能作为类的普通成员。

thread_local变量实例的初始化非常像静态变量，但有一点不同，thread_local变量必须为每个线程单独初始化一次，而不是仅在程序启动时初始化。这意味着在函数作用域声明的thread_local是安全的，而其他情况都会存在和静态变量类似的初始化顺序等一系列问题，thread_local变量的实例在它所在的线程终止时被销毁，因此它们不存在静态变量类似的析构顺序的问题。

优点：
thread_local是唯一一种在标准中支持的创建线程局部数据的方式。这种数据是线程安全的，因为其一个实例通常只有本线程才会访问，这在并发编程中非常有用。
缺点：
访问一个thread_local变量可能触发一些不可预测和不可控的代码被执行。并且thread_local变量实际上是全局变量，所以也存在作为全局变量的缺陷（除了线程不安全）。
一个thread_local变量所占用的内存大小（在最坏的情况）会随着线程数增加而成倍增长。
类的普通成员不能声明为thread_local。
thread_local的效率可能比不上一些编译器内置的intrinsics方法。
建议：
函数内部的thread_local变量不用考虑安全性问题，因此在函数内使用没有限制。注意，你可以用一个函数作用域的thread_local来模拟出类或命名空间作用域的thread_local：只需要通过函数或静态方法将之暴露出来即可:

Foo& MyThreadLocalFoo() {
  thread_local Foo result = ComplicatedInitialization();
  return result;
}

而如果你要声明一个类或命名空间作用域的thread_local变量，则必须给它初始化为一个真正编译时期的常量（例如不能存在动态初始化），为了保证这一点，这个变量必须用ABSL_CONST_INIT修饰（也可以用constexpr，但比较罕见）：

ABSL_CONST_INIT thread_local Foo foo = ...;