吴良超的学习笔记

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.hlogs.h 要好

  • 定义类时文件名一般成对出现,如 foo_bar.hfoo_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