28. 17. 用 sizeof(varname)代替 sizeof(type);
18. 只使用 Boost 中被认可的库。
Google C++编程风格指南(五)
命名约定
最重要的一致性规则是命名管理,命名风格直接可以直接确定命名实体是:类型、变量、函数、常量、宏等等,无需
查找实体声明,我们大脑中的模式匹配引擎依赖于这些命名规则。
命名规则具有一定随意性,但相比按个人喜好命名,一致性更重要,所以不管你怎么想,规则总归是规则。
1. 通用命名规则(General Naming Rules)
函数命名、变量命名、文件命名应具有描述性,不要过度缩写,类型和变量应该是名词,函数名可以用“命令性”动词。
如何命名:
尽可能给出描述性名称,不要节约空间,让别人很快理解你的代码更重要,好的命名选择:
int num_errors; // Good.
int num_completed_connections; // Good.
丑陋的命名使用模糊的缩写或随意的字符:
int n; // Bad - meaningless.
int nerr; // Bad - ambiguous abbreviation.
int n_comp_conns; // Bad - ambiguous abbreviation.
类型和变量名一般为名词:如 FileOpener 、num_errors。
函数名通常是指令性的,如 OpenFile()、set_num_errors() ,访问函数需要描述的更细致,要与其访问的变量
相吻合。
缩写:
除非放到项目外也非常明了,否则不要使用缩写,例如:
// Good
// These show proper names with no abbreviations.
int num_dns_connections; // Most people know what "DNS" stands for.
int price_count_reader; // OK, price count. Makes sense.
// Bad!
// Abbreviations can be confusing or ambiguous outside a small group.
int wgc_connections; // Only your group knows what this stands for.
29. int pc_reader; // Lots of things can be abbreviated "pc".
不要用省略字母的缩写:
int error_count; // Good.
int error_cnt; // Bad.
2. 文件命名(File Names)
文件名要全部小写,可以包含下划线(_)或短线(-),按项目约定来。
可接受的文件命名:
my_useful_class.cc
my-useful-class.cc
myusefulclass.cc
C++文件以.cc 结尾,头文件以.h 结尾。
不要使用已经存在于/usr/include 下的文件名(译者注,对 UNIX、Linux 等系统而言),如 db.h 。
通常,尽量让文件名更加明确,http_server_logs.h 就比 logs.h 要好,定义类时文件名一般成对出现,如
foo_bar.h 和 foo_bar.cc,对应类 FooBar 。
内联函数必须放在.h 文件中,如果内联函数比较短,就直接放在.h 中。如果代码比较长,可以放到以-inl.h 结尾
的文件中。对于包含大量内联代码的类,可以有三个文件:
url_table.h // The class declaration.
url_table.cc // The class definition.
url_table-inl.h // Inline functions that include lots of code.
参考第一篇-inl.h 文件一节。
3. 类型命名(Type Names)
类型命名每个单词以大写字母开头,不包含下划线:MyExcitingClass 、MyExcitingEnum。
所有类型命名——类、结构体、类型定义(typedef)、枚举——使用相同约定,例如:
// classes and structs
class UrlTable { ...
class UrlTableTester { ...
struct UrlTableProperties { ...
// typedefs
typedef hash_map<UrlTableProperties *, string> PropertiesMap;
33. 1. 注释风格(Comment Style)
使用// 或/* */ ,统一就好。
// 或/* */ 都可以,// 只是用的更加广泛,在如何注释和注释风格上确保统一。
2. 文件注释(File Comments)
在每一个文件开头加入版权公告,然后是文件内容描述。
法律公告和作者信息:
每一文件包含以下项,依次是:
1) 版权(copyright statement):如 Copyright 2008 Google Inc. ;
2) 许可版本(license boilerplate):为项目选择合适的许可证版本,如 Apache 2.0、BSD、LGPL、GPL;
3) 作者(author line):标识文件的原始作者。
如果你对其他人创建的文件做了重大修改,将你的信息添加到作者信息里,这样当其他人对该文件有疑问时可以知道
该联系谁。
文件内容:
每一个文件版权许可及作者信息后,都要对文件内容进行注释说明。
通常,.h 文件要对所声明的类的功能和用法作简单说明,.cc 文件包含了更多的实现细节或算法讨论,如果你感觉
这些实现细节或算法讨论对于阅读有帮助,可以把.cc 中的注释放到.h 中,并在.cc 中指出文档在.h 中。
不要单纯在.h 和.cc 间复制注释,复制的注释偏离了实际意义。
3. 类注释(Class Comments)
每个类的定义要附着描述类的功能和用法的注释。
// 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 GargantuanTable_Iterator {
...
};
34. 如果你觉得已经在文件顶部详细描述了该类,想直接简单的来上一句“完整描述见文件顶部”的话,还是多少在类中加
点注释吧。
如果类有任何同步前提(synchronization assumptions),文档说明之。如果该类的实例可被多线程访问,使用
时务必注意文档说明。
4. 函数注释(Function Comments)
函数声明处注释描述函数功能,定义处描述函数实现。
函数声明:
注释于声明之前,描述函数功能及用法,注释使用描述式("Opens the file")而非指令式("Open the file");注
释只是为了描述函数而不是告诉函数做什么。通常,注释不会描述函数如何实现,那是定义部分的事情。
函数声明处注释的内容:
1) inputs(输入)及 outputs(输出);
2) 对类成员函数而言:函数调用期间对象是否需要保持引用参数,是否会释放这些参数;
3) 如果函数分配了空间,需要由调用者释放;
4) 参数是否可以为 NULL ;
5) 是否存在函数使用的性能隐忧(performance implications);
6) 如果函数是可重入的(re-entrant),其同步前提(synchronization assumptions)是什么?
举例如下:
// 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;
但不要有无谓冗余或显而易见的注释,下面的注释就没有必要加上“returns false otherwise”,因为已经暗含其中了:
35. // Returns true if the table cannot hold any more entries.
bool IsTableFull();
注释构造/析构函数时,记住,读代码的人知道构造/析构函数是什么,所以“destroys this object”这样的注释是没
有意义的。说明构造函数对参数做了什么(例如,是否是指针的所有者)以及析构函数清理了什么,如果都是无关紧
要的内容,直接省掉注释,析构函数前没有注释是很正常的。
函数定义:
每个函数定义时要以注释说明函数功能和实现要点,如使用的漂亮代码、实现的简要步骤、如此实现的理由、为什么
前半部分要加锁而后半部分不需要。
不要从.h 文件或其他地方的函数声明处直接复制注释,简要说明函数功能是可以的,但重点要放在如何实现上。
5. 变量注释(Variable Comments)
通常变量名本身足以很好说明变量用途,特定情况下,需要额外注释说明。
类数据成员:
每个类数据成员(也叫实例变量或成员变量)应注释说明用途,如果变量可以接受 NULL 或-1 等警戒值(sentinel
values),须说明之,如:
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_;
全局变量(常量):
和数据成员相似,所有全局变量(常量)也应注释说明含义及用途,如:
// The total number of tests cases that we run through in this regression test.
const int kNumTestCases = 6;
6. 实现注释(Implementation Comments)
对于实现代码中巧妙的、晦涩的、有趣的、重要的地方加以注释。
代码前注释:
出彩的或复杂的代码块前要加注释,如:
// Divide result by two, taking into account that x
// contains the carry from the add.
36. for (int i = 0; i < result->size(); i++) {
x = (x << 8) + (*result)[i];
(*result)[i] = x >> 1;
x &= 1;
}
行注释:
比较隐晦的地方要在行尾加入注释,可以在代码之后空两格加行尾注释,如:
// If we have enough memory, mmap the data portion too.
mmap_budget = max<int64>(0, mmap_budget - index_->length());
if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock))
return; // Error already logged.
注意,有两块注释描述这段代码,当函数返回时注释提及错误已经被记入日志。
前后相邻几行都有注释,可以适当调整使之可读性更好:
...
DoSomething(); // Comment here so the comments line up.
DoSomethingElseThatIsLonger(); // Comment here so there are two spaces between
// the code and the comment.
...
NULL、true/false、1、2、3……:
向函数传入、布尔值或整数时,要注释说明含义,或使用常量让代码望文知意,比较一下:
bool success = CalculateSomething(interesting_value,
10,
false,
NULL); // What are these arguments??
和:
bool success = CalculateSomething(interesting_value,
10, // Default base value.
false, // Not the first time we're calling this.
NULL); // No callback.
使用常量或描述性变量:
const int kDefaultBaseValue = 10;
const bool kFirstTimeCalling = false;
Callback *null_callback = NULL;
bool success = CalculateSomething(interesting_value,
37. kDefaultBaseValue,
kFirstTimeCalling,
null_callback);
不要:
注意永远不要用自然语言翻译代码作为注释,要假设读你代码的人 C++比你强:D:
// Now go through the b array and make sure that if i occurs,
// the next element is i+1.
... // Geez. What a useless comment.
7. 标点、拼写和语法(Punctuation, Spelling and Grammar)
留意标点、拼写和语法,写的好的注释比差的要易读的多。
注释一般是包含适当大写和句点(.)的完整的句子,短一点的注释(如代码行尾的注释)可以随意点,依然要注意风
格的一致性。完整的句子可读性更好,也可以说明该注释是完整的而不是一点不成熟的想法。
虽然被别人指出该用分号(semicolon)的时候用了逗号(comma)有点尴尬。清晰易读的代码还是很重要的,适
当的标点、拼写和语法对此会有所帮助。
8. TODO 注释(TODO Comments)
对那些临时的、短期的解决方案,或已经够好但并不完美的代码使用 TODO 注释。
这样的注释要使用全大写的字符串 TODO ,后面括号(parentheses)里加上你的大名、邮件地址等,还可以加上冒
号(colon):目的是可以根据统一的 TODO 格式进行查找:
// 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.")。
______________________________________
译者:注释也是比较人性化的约定了:
1. 关于注释风格,很多 C++的 coders 更喜欢行注释,C coders 或许对块注释依然情有独钟,或者在文件头大
段大段的注释时使用块注释;
2. 文件注释可以炫耀你的成就,也是为了捅了篓子别人可以找你;
3. 注释要言简意赅,不要拖沓冗余,复杂的东西简单化和简单的东西复杂化都是要被鄙视的;
39. 和处理其编码,十六进制编码也可以,尤其是在增强可读性的情况下——如"xEFxBBxBF"是 Unicode 的
zero-width no-break space 字符,以 UTF-8 格式包含在源文件中是不可见的。
3. 空格还是制表位(Spaces vs. Tabs)
只使用空格,每次缩进 2 个空格。
使用空格进行缩进,不要在代码中使用 tabs,设定编辑器将 tab 转为空格。
译者注:在前段时间的关于 Debian 开发学习日记一文中,曾给出针对 C/C++编码使用的 vim 配置。
4. 函数声明与定义(Function Declarations and Definitions)
返回类型和函数名在同一行,合适的话,参数也放在同一行。
函数看上去像这样:
ReturnType ClassName::FunctionName(Type par_name1, Type par_name2) {
DoSomething();
...
}
如果同一行文本较多,容不下所有参数:
ReturnType ClassName::ReallyLongFunctionName(Type par_name1,
Type par_name2,
Type par_name3) {
DoSomething();
...
}
甚至连第一个参数都放不下:
ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
Type par_name1, // 4 space indent
Type par_name2,
Type par_name3) {
DoSomething(); // 2 space indent
...
}
注意以下几点:
1) 返回值总是和函数名在同一行;
2) 左圆括号(open parenthesis)总是和函数名在同一行;
40. 3) 函数名和左圆括号间没有空格;
4) 圆括号与参数间没有空格;
5) 左大括号(open curly brace)总在最后一个参数同一行的末尾处;
6) 右大括号(close curly brace)总是单独位于函数最后一行;
7) 右圆括号(close parenthesis)和左大括号间总是有一个空格;
8) 函数声明和实现处的所有形参名称必须保持一致;
9) 所有形参应尽可能对齐;
10) 缺省缩进为 2 个空格;
11) 独立封装的参数保持 4 个空格的缩进。
如果函数为 const 的,关键字 const 应与最后一个参数位于同一行。
// 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 {
...
}
如果有些参数没有用到,在函数定义处将参数名注释起来:
// Always have named parameters in interfaces.
class Shape {
public:
virtual void Rotate(double radians) = 0;
}
// Always have named parameters in the declaration.
class Circle : public Shape {
public:
virtual void Rotate(double radians);
}
// Comment out unused named parameters in definitions.
void Circle::Rotate(double /*radians*/) {}
41. // Bad - if someone wants to implement later, it's not clear what the
// variable means.
void Circle::Rotate(double) {}
译者注:关于 UNIX/Linux 风格为什么要把左大括号置于行尾(.cc 文件的函数实现处,左大括号位于行首),我
的理解是代码看上去比较简约,想想行首除了函数体被一对大括号封在一起之外,只有右大括号的代码看上去确实也
舒服;Windows 风格将左大括号置于行首的优点是匹配情况一目了然。
5. 函数调用(Function Calls)
尽量放在同一行,否则,将实参封装在圆括号中。
函数调用遵循如下形式:
bool retval = DoSomething(argument1, argument2, argument3);
如果同一行放不下,可断为多行,后面每一行都和第一个实参对齐,左圆括号后和右圆括号前不要留空格:
bool retval = DoSomething(averyveryveryverylongargument1,
argument2, argument3);
如果函数参数比较多,可以出于可读性的考虑每行只放一个参数:
bool retval = DoSomething(argument1,
argument2,
argument3,
argument4);
如果函数名太长,以至于超过行最大长度,可以将所有参数独立成行:
if (...) {
...
...
if (...) {
DoSomethingThatRequiresALongFunctionName(
very_long_argument1, // 4 space indent
argument2,
argument3,
argument4);
}
6. 条件语句(Conditionals)
更提倡不在圆括号中添加空格,关键字 else 另起一行。
42. 对基本条件语句有两种可以接受的格式,一种在圆括号和条件之间有空格,一种没有。
最常见的是没有空格的格式,那种都可以,还是一致性为主。如果你是在修改一个文件,参考当前已有格式;如果是
写新的代码,参考目录下或项目中其他文件的格式,还在徘徊的话,就不要加空格了。
if (condition) { // no spaces inside parentheses
... // 2 space indent.
} else { // The else goes on the same line as the closing brace.
...
}
如果你倾向于在圆括号内部加空格:
if ( condition ) { // spaces inside parentheses - rare
... // 2 space indent.
} else { // The else goes on the same line as the closing brace.
...
}
注意所有情况下 if 和左圆括号间有个空格,右圆括号和左大括号(如果使用的话)间也要有个空格:
if(condition) // Bad - space missing after IF.
if (condition){ // Bad - space missing before {.
if(condition){ // Doubly bad.
if (condition) { // Good - proper space after IF and before {.
有些条件语句写在同一行以增强可读性,只有当语句简单并且没有使用 else 子句时使用:
if (x == kFoo) return new Foo();
if (x == kBar) return new Bar();
如果语句有 else 分支是不允许的:
// Not allowed - IF statement on one line when there is an ELSE clause
if (x) DoThis();
else DoThat();
通常,单行语句不需要使用大括号,如果你喜欢也无可厚非,也有人要求 if 必须使用大括号:
if (condition)
DoSomething(); // 2 space indent.
if (condition) {
DoSomething(); // 2 space indent.
}
但如果语句中哪一分支使用了大括号的话,其他部分也必须使用:
43. // 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;
}
7. 循环和开关选择语句(Loops and Switch Statements)
switch 语句可以使用大括号分块;空循环体应使用{}或 continue。
switch 语句中的 case 块可以使用大括号也可以不用,取决于你的喜好,使用时要依下文所述。
如果有不满足 case 枚举条件的值,要总是包含一个 default(如果有输入值没有 case 去处理,编译器将报警)。
如果 default 永不会执行,可以简单的使用 assert:
switch (var) {
case 0: { // 2 space indent
... // 4 space indent
break;
}
case 1: {
...
break;
}
default: {
assert(false);
}
}
44. 空循环体应使用{}或 continue,而不是一个简单的分号:
while (condition) {
// Repeat test until it returns 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.
8. 指针和引用表达式(Pointers and Reference Expressions)
句点(. )或箭头(->)前后不要有空格,指针/地址操作符(*、& )后不要有空格。
下面是指针和引用表达式的正确范例:
x = *p;
p = &x;
x = r.y;
x = r->y;
注意:
1) 在访问成员时,句点或箭头前后没有空格;
2) 指针操作符* 或& 后没有空格。
在声明指针变量或参数时,星号与类型或变量名紧挨都可以:
// 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 &
同一个文件(新建或现有)中起码要保持一致。
译者注:个人比较习惯与变量紧挨的方式。
9. 布尔表达式(Boolean Expressions)
如果一个布尔表达式超过标准行宽(80 字符),如果断行要统一一下。
45. 下例中,逻辑与(&& )操作符总位于行尾:
if (this_one_thing > this_other_thing &&
a_third_thing == a_fourth_thing &&
yet_another & last_one) {
...
}
两个逻辑与(&& )操作符都位于行尾,可以考虑额外插入圆括号,合理使用的话对增强可读性是很有帮助的。
译者注:个人比较习惯逻辑运算符位于行首,逻辑关系一目了然,各人喜好而已,至于加不加圆括号的问题,如果你
对优先级了然于胸的话可以不加,但可读性总是差了些。
10. 函数返回值(Return Values)
return 表达式中不要使用圆括号。
函数返回时不要使用圆括号:
return x; // not return(x);
11. 变量及数组初始化(Variable and Array Initialization)
选择=还是()。
需要做二者之间做出选择,下面的形式都是正确的:
int x = 3;
int x(3);
string name("Some Name");
string name = "Some Name";
12. 预处理指令(Preprocessor Directives)
预处理指令不要缩进,从行首开始。
即使预处理指令位于缩进代码块中,指令也应从行首开始。
// Good - directives at beginning of line
if (lopsided_score) {
#if DISASTER_PENDING // Correct -- Starts at beginning of line
DropEverything();
#endif
46. BackToNormal();
}
// 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();
}
13. 类格式(Class Format)
声明属性依次序是 public: 、protected:、private:,每次缩进 1 个空格(译者注,为什么不是两个呢?也有人
提倡 private 在前,对于声明了哪些数据成员一目了然,还有人提倡依逻辑关系将变量与操作放在一起,都有道
理:-) )。
类声明(对类注释不了解的话,参考第六篇中的类注释一节)的基本格式如下:
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) 所以基类名应在 80 列限制下尽量与子类名放在同一行;
47. 2) 关键词 public:、protected: 、private:要缩进 1 个空格(译者注,MSVC 多使用 tab 缩进,且这三个关键
词没有缩进);
3) 除第一个关键词(一般是 public)外,其他关键词前空一行,如果类比较小的话也可以不空;
4) 这些关键词后不要空行;
5) public 放在最前面,然后是 protected 和 private ;
6) 关于声明次序参考第三篇声明次序一节。
14. 初始化列表(Initializer Lists)
构造函数初始化列表放在同一行或按四格缩进并排几行。
两种可以接受的初始化列表格式:
// When it all fits on one line:
MyClass::MyClass(int var) : some_var_(var), some_other_var_(var + 1) {
或
// When it requires multiple lines, indent 4 spaces, putting the colon on
// the first initializer line:
MyClass::MyClass(int var)
: some_var_(var), // 4 space indent
some_other_var_(var + 1) { // lined up
...
DoSomething();
...
}
15. 命名空间格式化(Namespace Formatting)
命名空间内容不缩进。
命名空间不添加额外缩进层次,例如:
namespace {
void foo() { // Correct. No extra indentation within namespace.
...
}
} // namespace
48. 不要缩进:
namespace {
// Wrong. Indented when it should not be.
void foo() {
...
}
} // namespace
16. 水平留白(Horizontal Whitespace)
水平留白的使用因地制宜。不要在行尾添加无谓的留白。
普通:
void f(bool b) { // Open braces should always have a space before them.
...
int i = 0; // Semicolons usually have no space before them.
int x[] = { 0 }; // Spaces inside braces for array initialization are
int x[] = {0}; // optional. If you use them, put them on both sides!
// Spaces around the colon in inheritance and initializer lists.
class Foo : public Bar {
public:
// For inline function implementations, put spaces between the braces
// and the implementation itself.
Foo(int b) : Bar(), baz_(b) {} // No spaces inside empty braces.
void Reset() { baz_ = 0; } // Spaces separating braces from implementation.
...
添加冗余的留白会给其他人编辑时造成额外负担,因此,不要加入多余的空格。如果确定一行代码已经修改完毕,将
多余的空格去掉;或者在专门清理空格时去掉(确信没有其他人在使用)。
循环和条件语句:
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) {
switch ( i ) { // Loops and conditions may have spaces inside