统一规范的代码风格在团队协作中非常重要,在若干的风格标准中,Google C++ Style 又是较为被认可的,本文是阅读了 Google C++ Style Guide 中第六(命名约定)、七(注释)、八(格式)章后的一些笔记,主要涉及代码的一些基本规范。需要注意的是,各种规范之间并没有绝对的好坏之分,只要团队保持一致即可。
命名约定
一般性命名规则
- 给出描述性的名称(某些为人熟知的词可用缩写如 DNS)
1 | // 使用 |
- 变量一般是名词(如上), 函数名一般是指令性的(如
open_file()、 set_num_errors()
)
文件命名
文件名要全部小写,可以包含下划线(_) , C++文件以
.cc
结尾,头文件以.h
结尾尽量让文件名更加明确, 如
http_server_logs.h
比logs.h
要好定义类时文件名一般成对出现,如
foo_bar.h
和foo_bar.cc
,对应类FooBar
类型命名
所有类型命名,包括类、结构体、类型定义(typedef)、枚举,均使用相同约定:每个单词以大写字母开头,不包含下划线,其实就是驼峰法, 如下
1 | // classes and structs |
变量命名
- 变量名一律小写,单词间以下划线相连,类的成员变量以下划线结尾,结构体的数据成员可以和普通变量一样,不用像类那样接下划线,如
1 | string table_name; // OK - uses underscore. |
- 对全局变量没有特别要求,少用就好,可以以
g_
或其他易与局部变量区分的标志为前缀
常量命名
- 在名称前加 k, 且 k 后接大写字母开头的单词, 如
kDaysInAWeek
函数命名
函数这里做了两种分类:普通函数(regular functions)和存取函数(accessors and mutators)
- 普通函数: 每个单词首字母大写,没有下划线, 如
MyExcitingMethod()
- 存取函数: 与变量名匹配:如
set_my_exciting_member_variable()
1 | class MyClass { |
枚举命名
- 枚举值应全部大写,单词间以下划线相连(宏的命名也与其保持一致):
MY_EXCITING_ENUM_VALUE
- 枚举名称属于类型,因此大小写混合, 即
UrlTableErrors
。
1 | enum UrlTableErrors { |
小结
总体规则:不要随意缩写,如果说 ChangeLocalValue 写作 ChgLocVal 还有情可原的话,把 ModifyPlayerName 写作 MdfPlyNm 就太过分了,除函数名可适当为动词外,其他命名尽量使用清晰易懂的名词
宏、枚举等使用全部大写+下划线;
变量(含类、结构体成员变量)、文件、命名空间、存取函数等使用全部小写+下划线 ,类成员变量以下划线结尾,全局变量以 g_开头;
普通函数、类型(含类与结构体、枚举类型)、常量等使用大小写混合,不含下划线;
注释
注释对保证代码可读性至为重要,当然也要记住,注释的确很重要,但最好的代码本身就是文档( 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 | // Iterates over the contents of a GargantuanTable. Sample usage: |
函数注释
注释于声明之前,描述函数功能及用法,注释使用描述式(”opens the file”)而非指令式(”open the file”);注释只是为了描述函数而不是告诉函数做什么。
1 | // Returns an iterator for this table. It is the client's |
函数定义处注释的内容:
每个函数定义时要以注释说明函数功能和实现要点,如使用的漂亮代码、实现的简要步骤、如此实现的理由、为什么前半部分要加锁而后半部分不需要。
简要说明函数功能是可以的,重点要放在如何实现上。
变量注释
通常变量名本身足以很好说明变量用途,特定情况下,需要额外注释说明
类数据成员
每个类数据成员(也叫实例变量或成员变量)应注释说明用途,如果变量可以接受 NULL 或-1等警戒值( sentinel values) ,须说明之,如:
1 | private: |
全局变量(常量)
和数据成员相似,所有全局变量(常量)也应注释说明含义及用途,如: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 | // TODO(kl@gmail.com): Use a "*" here for concatenation operator. |
如果加上是为了在“将来某一天做某事”,可以加上一个特定的时间(”Fix by November 2005”)或事件( “Remove this code when all clients can handle XML responses.”)。
格式
代码风格和格式确实比较随意,但一个项目中所有人遵循同一风格是非常容易的,作为个人未必同意下述格式规则的每一处,但整个项目服从统一的编程风格是很重要的,这样做才能让所有人在阅读和理解代码时更加容易。
空格还是制表位
只使用空格,每次缩进 2 个空格。
使用空格进行缩进,不要在代码中使用 tabs,设定编辑器将 tab 转为空格。
函数声明与定义
返回类型和函数名在同一行,合适的话,参数也放在同一行。
函数看上去像这样:
1 | ReturnType ClassName::FunctionName(Type par_name1, Type par_name2) { |
如果同一行文本较多,容不下所有参数:
1 | ReturnType ClassName::ReallyLongFunctionName(Type par_name1, |
甚至连第一个参数都放不下
1 | ReturnType LongClassName::ReallyReallyReallyLongFunctionName( |
注意以下几点
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 | if (x == kFoo) return new Foo(); |
如果语句有 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
5if (condition)
DoSomething(); // 2 space indent.
if (condition) {
DoSomething(); // 2 space indent.
}
如果语句中哪一分支使用了大括号的话,其他部分也必须使用
1 | // Not allowed - curly on IF but not ELSE |
循环和开关选择语句
switch 语句可以使用大括号分块;空循环体应使用{}或 continue
switch 语句中的 case 块可以使用大括号也可以不用,取决于你的喜好,使用时要依下文所述。
如果有不满足 case 枚举条件的值,要总是包含一个 default(如果有输入值没有 case 去处理,编译器将报警)。如果 default 永不会执行,可以简单的使用 assert:
1 | // switch 语句 |
指针和引用表达式
句点(.
)或箭头(->
)前后不要有空格,指针/地址操作符(*
、&
)后不要有空格
下面是指针和引用表达式的正确范例:
1 | x = *p; |
在声明指针变量或参数时,星号与类型或变量名紧挨都可以:
1 | // These are fine, space preceding. |
布尔表达式
如果一个布尔表达式超过标准行宽(80 字符),如果断行要统一一下。
下例中,逻辑与(&&
)操作符总位于行尾(可也考虑放在行首):
1 | if (this_one_thing > this_other_thing && |
变量及数组初始化
选择 =
或 ()
, 下面的形式都是正确的:1
2
3
4int x = 3;
int x(3);
string name("Some Name");
string name = "Some Name";
预处理指令
预处理指令不要缩进,从行首开始
即使预处理指令位于缩进代码块中,指令也应从行首开始。
1 | // Good - directives at beginning of line |
类格式
声明属性依次序是 public:、 protected:、 private:
, 每次缩进 1 个空格; 除第一个关键词(一般是 public)外,其他关键词前空一行,关键词后不要空行;
每一块中,声明次序一般如下:
1) typedefs 和 enums;
2) 常量;
3) 构造函数;
4) 析构函数;
5) 成员函数,含静态成员函数;
6) 数据成员,含静态数据成员。
1 | class MyClass : public OtherClass { |
命名空间格式化
命名空间不添加额外缩进层次,例如:
1 | namespace { |
水平留白
添加冗余的留白会给其他人编辑时造成额外负担,因此,不要加入多余的空格。如果确定一
行代码已经修改完毕,将多余的空格去掉;或者在专门清理空格时去掉(确信没有其他人在
使用)
一般情况
1 | void f(bool b) { // 大括号前需要有空格... |
循环和条件语句
1 | if (b) { // Space after the keyword in conditions and loops. |
操作符
赋值符号和二元操作符一般左右都带上空格,一元操作符则不用, 如下
1 | x = 0; // Assignment operators always have spaces around them. |
垂直留白
垂直留白越少越好。这不仅仅是规则而是原则问题了:不是非常有必要的话就不要使用空行。尤其是:
1)不要在两个函数定义之间空超过 2 行
2)函数体头、尾不要有空行,函数体中也不要随意添加空行。
3)基本原则是:同一屏可以显示越多的代码,程序的控制流就越容易理解。当然,过于密集的
代码块和过于疏松的代码块同样难看,取决于你的判断,但通常是越少越好。
函数头、尾不要有空行,如:
1 | void Function() { |
代码块头、尾不要有空行, 如:
1 | while (condition) { |
最后,有人根据这些规则总结了一张图,比较直观归纳了上面提到的各种规则风格,图片出自这里