吴良超的学习笔记

Google C++ Style Guide 阅读笔记

发表于 | ，

统一规范的代码风格在团队协作中非常重要，在若干的风格标准中，Google C++ Style 又是较为被认可的，本文是阅读了 Google C++ Style Guide 中第六(命名约定)、七(注释)、八(格式)章后的一些笔记，主要涉及代码的一些基本规范。需要注意的是，各种规范之间并没有绝对的好坏之分，只要团队保持一致即可。

命名约定

一般性命名规则

  • 给出描述性的名称(某些为人熟知的词可用缩写如 DNS)
1
2
3
4
5
6
7
// 使用
int num_errors; // Good.
int num_completed_connections; // Good.

// 不使用
int nerr; // Bad - ambiguous abbreviation.
int n_comp_conns; // Bad - ambiguous abbreviation.
  • 变量一般是名词(如上）， 函数名一般是指令性的（如 open_file()、 set_num_errors())

文件命名

  • 文件名要全部小写，可以包含下划线（_） , C++文件以 .cc 结尾，头文件以 .h 结尾

  • 尽量让文件名更加明确， 如 http_server_logs.h 比 logs.h 要好

  • 定义类时文件名一般成对出现，如 foo_bar.h 和 foo_bar.cc，对应类 FooBar

类型命名

所有类型命名，包括类、结构体、类型定义（typedef）、枚举，均使用相同约定：每个单词以大写字母开头，不包含下划线，其实就是驼峰法, 如下

1
2
3
4
5
6
7
8
// classes and structs
class UrlTable { ...
class UrlTableTester { ...
struct UrlTableProperties { ...
// typedefs
typedef hash_map<UrlTableProperties *, string> PropertiesMap;
// enums
enum UrlTableErrors { ...

变量命名

  • 变量名一律小写，单词间以下划线相连，类的成员变量以下划线结尾，结构体的数据成员可以和普通变量一样，不用像类那样接下划线，如
1
2
3
4
5
6
7
8
9
10
11
12
13
string table_name; // OK - uses underscore.
string tableName; // Bad - mixed case

class UrlTableProperties {
  string name_;
  int num_entries_;
  
}

struct UrlTableProperties {
  string name;
  int num_entries;
}
  • 对全局变量没有特别要求，少用就好，可以以 g_ 或其他易与局部变量区分的标志为前缀

常量命名

  • 在名称前加 k, 且 k 后接大写字母开头的单词, 如 kDaysInAWeek

函数命名

函数这里做了两种分类：普通函数(regular functions)和存取函数(accessors and mutators)

  1. 普通函数: 每个单词首字母大写，没有下划线, 如 MyExcitingMethod()
  2. 存取函数: 与变量名匹配：如 set_my_exciting_member_variable()
1
2
3
4
5
6
7
8
9
class MyClass {
  public:
    ...
    int num_entries() const { return num_entries_; }
    void set_num_entries(int num_entries) { num_entries_ = num_entries; }
  
  private:
   int num_entries_;
}

枚举命名

  • 枚举值应全部大写，单词间以下划线相连(宏的命名也与其保持一致)： MY_EXCITING_ENUM_VALUE
  • 枚举名称属于类型，因此大小写混合, 即 UrlTableErrors。
1
2
3
4
5
enum UrlTableErrors {
    OK = 0,
    ERROR_OUT_OF_MEMORY,
    ERROR_MALFORMED_INPUT,
};

小结

  1. 总体规则：不要随意缩写，如果说 ChangeLocalValue 写作 ChgLocVal 还有情可原的话，把 ModifyPlayerName 写作 MdfPlyNm 就太过分了，除函数名可适当为动词外，其他命名尽量使用清晰易懂的名词

  2. 宏、枚举等使用全部大写+下划线；

  3. 变量（含类、结构体成员变量）、文件、命名空间、存取函数等使用全部小写+下划线 ，类成员变量以下划线结尾，全局变量以 g_开头；

  4. 普通函数、类型（含类与结构体、枚举类型）、常量等使用大小写混合，不含下划线；

注释

注释对保证代码可读性至为重要，当然也要记住，注释的确很重要，但最好的代码本身就是文档（ self-documenting），类型和变量命名意义明确要比通过注释解释模糊的命名好得多。

下面的规则描述了应该注释什么、注释在哪儿。比通过注释解释模糊的命名好得多

文件注释

在每一个文件开头加入版权公告，然后是文件内容描述。

1. 版权公告

每一文件包含以下项，依次是：
1) 版权（copyright statement） ：如 Copyright 2008 Google Inc.；
2) 许可版本（license boilerplate） ：为项目选择合适的许可证版本，如 Apache 2.0、BSD、 LGPL、 GPL；
3) 作者（author line） ：标识文件的原始作者

如果你对其他人创建的文件做了重大修改，将你的信息添加到作者信息里，这样当其他人对该文件有疑问时可以知道该联系谁。

2. 文件内容

每一个文件版权许可及作者信息后，都要对文件内容进行注释说明。

1）.h 文件要对所声明的类的功能和用法作简单说明
2) .cc 文件包含了更多的实现细节或算法讨论，如果你感觉这些实现细节或算法讨论对于阅读有帮助，可以把 .cc 中的注释放到 .h 中，并在 .cc 中指出文档在 .h 中。

不要单纯在 .h 和 .cc 间复制注释，复制的注释偏离了实际意义。

类注释

每个类的定义要附着描述类的功能和用法的注释, 如

1
2
3
4
5
6
7
8
9
// Iterates over the contents of a GargantuanTable. Sample usage:
// GargantuanTable_Iterator* iter = table->NewIterator();
// for (iter->Seek("foo"); !iter->done(); iter->Next()) {
// process(iter->key(), iter->value());
// }
// delete iter;
class GargantuanTableIterator {
  ...
};

函数注释

注释于声明之前，描述函数功能及用法，注释使用描述式（”opens the file”）而非指令式（”open the file”）；注释只是为了描述函数而不是告诉函数做什么。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Returns an iterator for this table. It is the client's
// responsibility to delete the iterator when it is done with it,
// and it must not use the iterator once the GargantuanTable object
// on which the iterator was created has been deleted.
//
// The iterator is initially positioned at the beginning of the table.
//
// This method is equivalent to:
// Iterator* iter = table->NewIterator();
// iter->Seek("");
// return iter;// If you are going to immediately seek to another place in the
// returned iterator, it will be faster to use NewIterator()
// and avoid the extra seek.
Iterator* GetIterator() const;

函数定义处注释的内容:

每个函数定义时要以注释说明函数功能和实现要点，如使用的漂亮代码、实现的简要步骤、如此实现的理由、为什么前半部分要加锁而后半部分不需要。

简要说明函数功能是可以的，重点要放在如何实现上。

变量注释

通常变量名本身足以很好说明变量用途，特定情况下，需要额外注释说明

类数据成员
每个类数据成员（也叫实例变量或成员变量）应注释说明用途，如果变量可以接受 NULL 或-1等警戒值（ sentinel values） ，须说明之，如：

1
2
3
4
5
private:
  // Keeps track of the total number of entries in the table.
  // Used to ensure we do not go over the limit. -1 means
  // that we don't yet know how many entries the table has.
  int num_total_entries_;

全局变量（常量）

和数据成员相似，所有全局变量（常量）也应注释说明含义及用途，如：

1
2
// The total number of tests cases that we run through in this regression test.
const int kNumTestCases = 6

TODO 注释

对那些临时的、短期的解决方案，或已经够好但并不完美的代码使用 TODO 注释。

这样的注释要使用全大写的字符串 TODO，后面括号里加上你的大名、邮
件地址等，还可以加上冒号目的是可以根据统一的 TODO 格式进行查找：

1
2
// TODO(kl@gmail.com): Use a "*" here for concatenation operator.
// TODO(Zeke) change this to use relations.

如果加上是为了在“将来某一天做某事”，可以加上一个特定的时间（”Fix by November 2005”）或事件（ “Remove this code when all clients can handle XML responses.”）。

格式

代码风格和格式确实比较随意，但一个项目中所有人遵循同一风格是非常容易的，作为个人未必同意下述格式规则的每一处，但整个项目服从统一的编程风格是很重要的，这样做才能让所有人在阅读和理解代码时更加容易。

空格还是制表位

只使用空格，每次缩进 2 个空格。

使用空格进行缩进，不要在代码中使用 tabs，设定编辑器将 tab 转为空格。

函数声明与定义

返回类型和函数名在同一行，合适的话，参数也放在同一行。
函数看上去像这样：

1
2
3
4
ReturnType ClassName::FunctionName(Type par_name1, Type par_name2) {
  DoSomething();
  ...
}

如果同一行文本较多，容不下所有参数：

1
2
3
4
5
6
ReturnType ClassName::ReallyLongFunctionName(Type par_name1,
                                             Type par_name2,
                                             Type par_name3) {
  DoSomething();
  ...
}

甚至连第一个参数都放不下

1
2
3
4
5
6
7
ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
    Type par_name1, // 4 space indent
    Type par_name2,
    Type par_name3) {
  DoSomething(); // 2 space indent
...
}

注意以下几点
1) 返回值总是和函数名在同一行；
2) 左圆括号（ open parenthesis） 总是和函数名在同一行；
3) 函数名和左圆括号间没有空格；
4) 圆括号与参数间没有空格；
5) 左大括号总在最后一个参数同一行的末尾处；
6) 右大括号总是单独位于函数最后一行；
7) 右圆括号和左大括号间总是有一个空格；
8) 函数声明和实现处的所有形参名称必须保持一致；
9) 所有形参应尽可能对齐；
10) 缺省缩进为 2 个空格；
11) 独立封装的参数保持 4 个空格的缩进。

如果函数为 const 的，关键字 const 应与最后一个参数位于同一行。

1
2
3
4
5
6
7
8
9
10
// Everything in this function signature fits on a single line
ReturnType FunctionName(Type par) const {
  ...
}
// This function signature requires multiple lines, but
// the const keyword is on the line with the last parameter.
ReturnType ReallyLongFunctionName(Type par1,
                                  Type par2) const {
...
}

函数调用 的风格跟定义一样

条件语句

有些条件语句写在同一行以增强可读性，只有当语句简单并且没有使用 else 子句时使用：

1
2
if (x == kFoo) return new Foo();
if (x == kBar) return new Bar();

如果语句有 else 分支是不允许的：

1
2
3
// Not allowed - IF statement on one line when there is an ELSE clause
if (x) DoThis();
else DoThat();

通常，单行语句不需要使用大括号，如果你喜欢也无可厚非，也有人要求 if 必须使用大括
号：

1
2
3
4
5
if (condition)
  DoSomething(); // 2 space indent.
if (condition) {
  DoSomething(); // 2 space indent.
}

如果语句中哪一分支使用了大括号的话，其他部分也必须使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Not allowed - curly on IF but not ELSE
if (condition) {
  foo;
} else
  bar;
  
// Not allowed - curly on ELSE but not IF
if (condition)
  foo;
else {
  bar;
}

// Curly braces around both IF and ELSE required because
// one of the clauses used braces.
if (condition) {
  foo;
} else {
  bar;
}

循环和开关选择语句

switch 语句可以使用大括号分块；空循环体应使用{}或 continue

switch 语句中的 case 块可以使用大括号也可以不用，取决于你的喜好，使用时要依下文所述。

如果有不满足 case 枚举条件的值，要总是包含一个 default（如果有输入值没有 case 去处理，编译器将报警）。如果 default 永不会执行，可以简单的使用 assert：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// switch 语句
switch (var) {
  case 0: { // 2 space indent
      ... // 4 space indent
      break;
  }
  case 1: {
      ...
      break;
  }
  default: {
      assert(false);
  }
}

// 空循环体
for (int i = 0; i < kSomeNumber; ++i) {} // Good - empty body.
while (condition) continue; // Good - continue indicates no logic.
while (condition); // Bad - looks like part of do/while loop.

指针和引用表达式

句点（.）或箭头（->）前后不要有空格，指针/地址操作符（*、&）后不要有空格

下面是指针和引用表达式的正确范例：

1
2
3
4
x = *p;
p = &x;
x = r.y;
x = r->y;

在声明指针变量或参数时，星号与类型或变量名紧挨都可以：

1
2
3
4
5
6
7
8
// These are fine, space preceding.
char *c;
const string &str;
// These are fine, space following.
char* c; // but remember to do "char* c, *d, *e, ...;"!
const string& str;
char * c; // Bad - spaces on both sides of *
const string & str; // Bad - spaces on both sides of &

布尔表达式

如果一个布尔表达式超过标准行宽（80 字符），如果断行要统一一下。
下例中，逻辑与（&&）操作符总位于行尾(可也考虑放在行首)：

1
2
3
4
5
if (this_one_thing > this_other_thing &&
    a_third_thing == a_fourth_thing &&
    yet_another & last_one) {
  ...
}

变量及数组初始化

选择 = 或 (), 下面的形式都是正确的：

1
2
3
4
int x = 3;
int x(3);
string name("Some Name");
string name = "Some Name";

预处理指令

预处理指令不要缩进，从行首开始

即使预处理指令位于缩进代码块中，指令也应从行首开始。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Good - directives at beginning of line
  if (lopsided_score) {
#if DISASTER_PENDING // Correct -- Starts at beginning of line
    DropEverything();
#endifBackToNormal();
  }
  
 
// Bad - indented directives
  if (lopsided_score) {
    #if DISASTER_PENDING // Wrong! The "#if" should be at beginning of line
      DropEverything();
    #endif // Wrong! Do not indent "#endif"
      BackToNormal();
}

类格式

声明属性依次序是 public:、 protected:、 private:, 每次缩进 1 个空格; 除第一个关键词（一般是 public）外，其他关键词前空一行，关键词后不要空行；

每一块中，声明次序一般如下：

1) typedefs 和 enums；
2) 常量；
3) 构造函数；
4) 析构函数；
5) 成员函数，含静态成员函数；
6) 数据成员，含静态数据成员。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
class MyClass : public OtherClass {
 public: // Note the 1 space indent!
   MyClass(); // Regular 2 space indent.
   explicit MyClass(int var);
   ~MyClass() {}
   
   void SomeFunction();
   void SomeFunctionThatDoesNothing() {
   }
   void set_some_var(int var) { some_var_ = var; }
   int some_var() const { return some_var_; }
 
 private:
   bool SomeInternalFunction();
   int some_var_;
   int some_other_var_;
   DISALLOW_COPY_AND_ASSIGN(MyClass);
 };

命名空间格式化

命名空间不添加额外缩进层次，例如：

1
2
3
4
5
6
7
8
9
10
11
12
namespace {
void foo() { // Correct. No extra indentation within namespace.
...
} 
} // namespace
    
namespace {
  // Wrong. Indented when  it should not be.
  void foo() {
    ...
  }
} // namespace

水平留白

添加冗余的留白会给其他人编辑时造成额外负担，因此，不要加入多余的空格。如果确定一
行代码已经修改完毕，将多余的空格去掉；或者在专门清理空格时去掉（确信没有其他人在
使用）

一般情况

1
2
3
4
void f(bool b) { // 大括号前需要有空格...
int i = 0; // 分号前一般没空格
int x[] = {0}; // 初始化数组的分号的空格可选
int x[] = { 0 }; // 要使用的话，两边都加上

循环和条件语句

1
2
3
4
5
6
if (b) { // Space after the keyword in conditions and loops.
} else { // Spaces around else.
}
while (test) {} // There is usually no space inside parentheses.
switch (i) {
for (int i = 0; i < 5; ++i) {

操作符

赋值符号和二元操作符一般左右都带上空格，一元操作符则不用, 如下

1
2
3
4
5
x = 0; // Assignment operators always have spaces around them.
v = w*x + y/z; // but it's okay to remove spaces around factors.
v = w * (x + z); // Parentheses should have no spaces inside them
x = -5; // No spaces separating unary operators and their
++x; // arguments.

垂直留白

垂直留白越少越好。这不仅仅是规则而是原则问题了：不是非常有必要的话就不要使用空行。尤其是：

1）不要在两个函数定义之间空超过 2 行
2）函数体头、尾不要有空行，函数体中也不要随意添加空行。
3）基本原则是：同一屏可以显示越多的代码，程序的控制流就越容易理解。当然，过于密集的
代码块和过于疏松的代码块同样难看，取决于你的判断，但通常是越少越好。

函数头、尾不要有空行，如：

1
2
3
4
5
void Function() {

  // Unnecessary blank lines before and after

}

代码块头、尾不要有空行, 如：

1
2
3
4
5
6
7
8
while (condition) {
  // Unnecessary blank line after

}
if (condition) {

  // Unnecessary blank line before
}

最后，有人根据这些规则总结了一张图，比较直观归纳了上面提到的各种规则风格，图片出自这里

style image