GoogleCpp风格指南 8)格式 _part1
8 格式 Formatting
代码风格和格式确实比较随意, 但一个项目中所有人遵循同一风格是非常容易的; 个体未必同意下述每一处格式规则, 但整个项目服从统一的编程风格是很重要的, 只有这样才能让所有人很轻松地阅读和理解代码;
我们写了一个 settings file for emacs [http://google-styleguide.googlecode.com/svn/trunk/google-c-style.el] 帮助你正确的格式化代码;
8.1 行长度 Line Length
Tip 每一行代码字符数不超过80;
我们也认识到这条规则是有争议的controversial, 但很多已有代码都已经遵照adheres这一规则, 我们感觉一致性更重要;
优点:
提倡该原则的人主张强迫他们调整编辑器窗口大小很野蛮; 很多人同时并排开几个代码窗口, 根本没有多余空间拉伸窗口; 大家都把窗口尺寸加以限定, 并且80列宽是传统标准, 为什么要改变呢? [分辨率越来越大, IDE中字体可以改小...]
缺点:
反对该原则的人则认为更宽的代码更易阅读; 80列的限制是上个世纪60年代的大型机mainframes的古板缺陷throwback hidebound, 现代设备具有更宽的显示屏, 很轻松的可以显示更多代码;
结论:
80个字符是最大值;
特例:
- 如果一行注释包含了超过80字符的命令或URL, 出于复制粘贴的方便允许该行超过80字符;
- 包含长路径的 #include语句可以超出80列, 但应尽量避免; [注意系统最大路径字符长度]
- 头文件保护 header guards 可以无视该原则;
8.2 非ASCII字符 Non-ASCII Characters
Tip 尽量不使用非ASCII字符, 使用时必须使用UTF-8编码; [http://en.wikipedia.org/wiki/UTF-8 ]
即使是英文, 也不应该将用户界面的文本硬编码hard-code到源代码中, 因此非ASCII字符要少用; 特殊情况下可以适当包含此类字符; 如, 代码分析parse外部数据文件foreign sources时, 可以适当硬编码数据文件中作为分隔符的delimiter非ASCII字符串; 更常见的是(不需要本地化的)单元测试代码可能包含非ASCII字符串; 此类情况下, 应使用UTF-8编码, 因为很多工具都可以encoding理解和处理UTF-8编码;
十六进制编码Hex encoding也可以, 能增强可读性的情况下尤其鼓励--比如 "\xEF\xBB\xBF"(简化版u8"\uFEFF")在Unicode中是零宽度 无间断的间隔符号Unicode zero-width no-break space character, 如果不用十六进制直接放在UTF-8格式的源文件中, 是看不到的; (译注: "\xEF\xBB\xBF"通常用作 UTF-8 with BOM编码标记); [https://docs.moodle.org/27/en/UTF-8_and_BOM#What_does_BOM_mean.3F ]
[Add]
使用 u8前缀来确保字符串字面量string literal包含 \uXXXX 转义escape的语句是按照UTF-8编码的; 不要讲它使用在包含非ASCII字母的字符串编码中, 如果编译器没有将源码文件作为UTF-8解析interpret的话, 那样会造成不正确的输出;
不要使用C++11 char16_t和char32_t字符类型, 它们是为非UTF-8文字准备的; 类似的原因你也不该使用wchar_t(除非你在写Windows API相关的代码, 将wchar_t作为扩展使用)
<<<
8.3 空格还是制表位 Spaces vs. Tabs
Tip 只使用空格, 每次缩进2个空格;
我们使用空格缩进, 不要在代码中使用制表符, 你应该设置编辑器, 将制表符转为空格; [为了干净的diff]
8.4 函数声明与定义 Function Declarations and Definitions
Tip 返回类型和函数名在同一行, 参数也尽量放在同一行;
[Add]形参和实参一样, 如果不能放同一行才换行;<<
函数看上去像这样:
|
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();
...
}
|
[Add]
|
1
2
3
4
5
|
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
...
}
|
注意以下几点:
- 返回值总是和函数名在同一行;
[Add]
-如果无法放在同一行, 将返回值类型和函数名分成两行;
- 如果将返回值和函数定义或声明分开了, 不要缩进 indent;
<<<
- 左圆括open parentheses号总是和函数名在同一行, ;
- 圆括号与参数间没有空格;
- 左花括号open curly brace总在最后一个参数同一行的末尾处;
- 右花括号close curly brace is总是单独位于函数最后一行, 或者(其他允许的风格)和左花括号同一行;
- 右圆括号和左花括号间总是有一个空格;
- 函数声明和实现处的所有形参名称必须保持一致; [声明可以不用形参]
- 所有形参应尽可能对齐aligned;
- 缺省缩进为2个空格;
- 换行后的参数保持4个空格的缩进;
[Remove]
如果函数声明成const, 关键字const应与最后一个参数位于同一行:
|
1
2
3
4
5
6
7
8
9
10
11
|
// 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
{
...
}
|
<<<
如果有些参数没有用到, 在函数定义出将参数名注释起来:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
// 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*/
) {}
|
[有专门的 #define UNUSED(x) (void)(x) 宏处理这类参数, Qt有 Q_UNUSED]
WARNING:
|
1
2
3
|
// Bad - if someone wants to implement later, it's not clear what the
// variable means.
void
Circle::Rotate(
double
) {}
|
[Add]
Lambda Expressions
参数和函数体的格式, 就像一般的逗号分隔列;
对于传引用捕获by-reference captures, 不要在引用符号ampersand (&)和变量名之间加空格;
|
1
2
|
int
x = 0;
auto
add_to_x = [&x](
int
n) { x += n; };
|
简短的lambda可以作为函数实参写成内联inline的;
|
1
2
3
4
5
6
|
std::set<
int
> blacklist = {7, 8, 9};
std::vector<
int
> digits = {3, 9, 1, 8, 4, 7, 1};
digits.erase(std::remove_if(digits.begin(), digits.end(), [&blacklist](
int
i) {
return
blacklist.find(i) != blacklist.end();
}),
digits.end());
|
<<<
8.5 函数调用 Function Calls
Tip 尽量放在同一行, 否则, 将实参封装在圆括号中;
[Add] 或者将实参换行, 4个空格缩进, 然后每次都一样缩进; 不考虑其他情况, 使用最小的行数, 可以适当将多个实参放在同一行; <<<
函数调用遵循如下形式:
|
1
|
bool
retval = DoSomething(argument1, argument2, argument3);
|
如果同一行放不下, 可断为多行, 后面subsequent每一行都和第一个实参对齐, 左圆括号open paren和右圆括号close paren前不要留空格:
|
1
2
|
bool
retval = DoSomething(averyveryveryverylongargument1,
argument2, argument3);
|
如果函数名非常长, 以至于超过行最大长度, 可以将所有参数独立成行:
|
1
2
3
4
5
6
7
8
9
10
|
if
(...) {
...
...
if
(...) {
DoSomethingThatRequiresALongFunctionName(
very_long_argument1,
// 4 space indent
argument2,
argument3,
argument4);
}
|
[Add]
参数可以放在随后的行中, 有4个空格的缩进;
|
1
2
3
4
5
|
if
(...) {
DoSomething(
argument1, argument2,
// 4 space indent
argument3, argument4);
}
|
尝试将多个实参放在单行以减少调用函数的行数, 除非阅读起来困难; 有发现显式每行严格放一个实参更易阅读而且容易修改; 我们要优先考虑方便修改, 然后才是易于阅读, 大多数可读性问题可以留给addressed今后的技术来解决;
如果在单行有多个实参, 复杂度和由多个参数组成的容易混淆的表达式使得可读性变差, 试着创建描述性变量来获取参数值;
|
1
2
|
int
my_heuristic = scores[x] * y + bases[x];
bool
retval = DoSomething(my_heuristic, x, y, z);
|
或者将易混淆的实参放在独立行, 写下说明性注释;
|
1
2
|
bool
retval = DoSomething(scores[x] * y + bases[x],
// Score heuristic.
x, y, z);
|
如果还是有一个实参放在独立一行中可读性有重大改善, 那么就将它放在独立行; 可读性比普遍方针general policy更重要;
有时候结从构体获得的实参对于可读性很重要; 这些情况下, 可以根据结构来定义参数格式:
|
1
2
3
4
|
// Transform the widget by a 3x3 matrix.
my_widget.Transform(x1, x2, x3,
y1, y2, y3,
z1, z2, z3);
|
<<<
[Add]
Braced Initializer List Format
braced initializer list的格式就像函数调用格式一样;
如果braced list之后跟一个名字(e.g. 类型或变量名), 就像 {} 将函数调用包含起来一样格式化它; 如果没有名字, 就当作一个0长度的名字;
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
|
// Examples of braced init list on a single line.
return
{foo, bar};
functioncall({foo, bar});
pair<
int
,
int
> p{foo, bar};
// When you have to wrap.
SomeFunction(
{
"assume a zero-length name before {"
},
some_other_function_parameter);
SomeType variable{
some, other, values,
{
"assume a zero-length name before {"
},
SomeOtherType{
"Very long string requiring the surrounding breaks."
,
some, other values},
SomeOtherType{
"Slightly shorter string"
,
some, other, values}};
SomeType variable{
"This is too long to fit all in one line"
};
MyType m = {
// Here, you could also break before {.
superlongvariablename1,
superlongvariablename2,
{
short
, interior, list},
{interiorwrappinglist,
interiorwrappinglist2}};
|
<<<
8.6 条件语句 Conditionals
Tip 倾向于不在圆括号内使用空格; 关键字 else另起一行, 和if在不同行;
对基本条件语句有两种可以接受的格式; 一种在圆括号和条件之间有空格, 另一种没有;
最常见的是没有空格的格式, 哪种都可以, 但保持一致性; 如果你是在修改一个文件, 参考当前已有格式, 如果是写新的代码, 参考目录下或项目中其他文件; 犹豫不定的话, 就不要加空格了;
|
1
2
3
4
5
|
if
(condition) {
// no spaces inside parentheses
...
// 2 space indent.
}
else
{
// The else goes on the same line as the closing brace.
...
}
|
如果你更喜欢在圆括号内部加空格:
|
1
2
3
4
5
|
if
( condition ) {
// spaces inside parentheses - rare
...
// 2 space indent.
}
else
{
// The else goes on the same line as the closing brace.
...
}
|
注意所有情况下 if 和左圆括号间都有个空格; 右圆括号和左花括号之间也要有个空格:
WARNING:
|
1
2
3
|
if
(condition)
// Bad - space missing after IF.
if
(condition){
// Bad - space missing before {.
if
(condition){
// Doubly bad.
|
正确:
|
1
|
if
(condition) {
// Good - proper space after IF and before {.
|
如果能增强可读性, 简短的条件语句允许写在同一行; 只有当语句简单并且没有使用 else子句clause时使用:
|
1
2
|
if
(x == kFoo)
return
new
Foo();
if
(x == kBar)
return
new
Bar();
|
如果有 else分支则不允许:
WARNING:
|
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
6
|
if
(condition)
DoSomething();
// 2 space indent.
if
(condition) {
DoSomething();
// 2 space indent.
}
|
但如果语句中某个 if-else分支使用了大括号的话, 其他分支也必须使用:
WARNING:
|
1
2
3
4
5
6
7
8
9
10
11
12
|
// 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;
}
|
正确:
|
1
2
3
4
5
6
7
|
// Curly braces around both IF and ELSE required because
// one of the clauses used braces.
if
(condition) {
foo;
}
else
{
bar;
}
|
8.7 循环和开关选择语句 Loops and Switch Statements
Tip switch语句可以使用花括号分段; [Add] 注释贯穿在不同的case中; 对于单个语句的循环, 花括号是可选的; <<< 空循环体应使用 {} 或 continue;
switch语句中的 case块可以使用大括号也可以不用, 取决于个人喜好, 如果用的话, 要按照下文所述的方法;
如果有不满足 case条件的枚举值, switch应该总是包含一个 default匹配(如果有输入值没有case去处理, 编译器将报警); 如果 default应该永远执行不到, 简单的加条 assert;
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
switch
(var) {
case
0: {
// 2 space indent
...
// 4 space indent
break
;
}
case
1: {
...
break
;
}
default
: {
assert
(
false
);
}
}
|
[Add]
大括号对单语句循环来说是可选的;
|
1
2
3
4
5
6
|
for
(
int
i = 0; i < kSomeNumber; ++i)
printf
(
"I love you\n"
);
for
(
int
i = 0; i < kSomeNumber; ++i) {
printf
(
"I take it back\n"
);
}
|
<<<
空循环体应该使用 {} 或 continue, 而不是一个简单的分号semicolon:
|
1
2
3
4
5
|
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.
|
[分号容易被忽略...但是可以作为一个语句]
WARNING:
|
1
|
while
(condition);
// Bad - looks like part of do/while loop.
|
8.8 指针和引用表达式 Pointer and Reference Expressions
Tip 句点或箭头前后不要有空格; 指针/地址操作符(*, &)之后不能有空格;
下面是指针和引用表达式的正确使用范例:
|
1
2
3
4
|
x = *p;
p = &x;
x = r.y;
x = r->y;
|
注意
- 在访问成员时, 句点或箭头前后没有空格;
- 在指针操作符 * 或 & 后没有空格;
在声明指针变量或参数时, 星号asterisk与类型或变量名紧挨adjacent都可以:
|
1
2
3
4
5
6
7
|
// 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;
|
WARNING:
|
1
2
|
char
* c;
// Bad - spaces on both sides of *
const
string & str;
// Bad - spaces on both sides of &
|
在单个文件内要保持风格一致, 所以如果是修改现有文件, 要遵照该文件的风格;
---YCR---