document/zh-google-styleguide

Fork 0

mirror of https://github.com/zh-google-styleguide/zh-google-styleguide.git synced 2025-02-19 20:50:10 +08:00

Isaac Ge 287c39937c formatting.rst: 增加「译者（acgtyrant）笔记」

2015-07-28 20:03:12 +08:00

30 KiB

Raw Blame History

8. 格式

代码风格和格式确实比较随意, 但一个项目中所有人遵循同一风格是非常容易的. 个体未必同意下述每一处格式规则, 但整个项目服从统一的编程风格是很重要的, 只有这样才能让所有人能很轻松的阅读和理解代码.

另外, 我们写了一个 emacs 配置文件来帮助你正确的格式化代码.

8.1. 行长度

Tip

每一行代码字符数不超过 80.

我们也认识到这条规则是有争议的, 但很多已有代码都已经遵照这一规则, 我们感觉一致性更重要.

优点:

提倡该原则的人主张强迫他们调整编辑器窗口大小很野蛮. 很多人同时并排开几个代码窗口, 根本没有多余空间拉伸窗口. 大家都把窗口最大尺寸加以限定, 并且 80 列宽是传统标准. 为什么要改变呢?

缺点:

反对该原则的人则认为更宽的代码行更易阅读. 80 列的限制是上个世纪 60 年代的大型机的古板缺陷; 现代设备具有更宽的显示屏, 很轻松的可以显示更多代码.

结论:

80 个字符是最大值.

特例:

如果一行注释包含了超过 80 字符的命令或 URL, 出于复制粘贴的方便允许该行超过 80 字符.

包含长路径的 #include 语句可以超出80列. 但应该尽量避免.

头文件保护 <define_guard> 可以无视该原则.

8.2. 非 ASCII 字符

Tip

尽量不使用非 ASCII 字符, 使用时必须使用 UTF-8 编码.

即使是英文, 也不应将用户界面的文本硬编码到源代码中, 因此非 ASCII 字符要少用. 特殊情况下可以适当包含此类字符. 如, 代码分析外部数据文件时, 可以适当硬编码数据文件中作为分隔符的非 ASCII 字符串; 更常见的是 (不需要本地化的) 单元测试代码可能包含非 ASCII 字符串. 此类情况下, 应使用 UTF-8 编码, 因为很多工具都可以理解和处理 UTF-8 编码.

十六进制编码也可以, 能增强可读性的情况下尤其鼓励 —— 比如 "\xEF\xBB\xBF" 在 Unicode 中是 零宽度无间断 的间隔符号, 如果不用十六进制直接放在 UTF-8 格式的源文件中, 是看不到的.

(yospaly 注: "\xEF\xBB\xBF" 通常用作 UTF-8 with BOM 编码标记)

用 u8 前缀以把带 uXXXX 转义序列的字符串字面值编码成 UTF-8. 不要用在本身就带 UTF-8 字符的字符串字面值上，因为如果编译器不把源代码识别成 UTF-8, 输出就会出错。

别用 C++11 的 char16_t 和 char32_t, 它们和 UTF-8 文本没有关系，wchar_t 同理，除非您写的代码要调用 Windows API, 后者有用到 wchar_t 扩展。

8.3. 空格还是制表位

Tip

只使用空格, 每次缩进 2 个空格.

我们使用空格缩进. 不要在代码中使用制符表. 你应该设置编辑器将制符表转为空格.

8.4. 函数声明与定义

Tip

返回类型和函数名在同一行, 参数也尽量放在同一行，如果放不下就对形参分行。

函数看上去像这样:

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
    ...
}

注意以下几点:

如果返回类型和函数名在一行放不下，分行。

如果返回类型那个与函数声明或定义分行了，不要缩进。

左圆括号总是和函数名在同一行;

函数名和左圆括号间没有空格;

圆括号与参数间没有空格;

左大括号总在最后一个参数同一行的末尾处;

如果其它风格规则允许的话，右大括号总是单独位于函数最后一行，或者与左大括号同一行。

右大括号和左大括号间总是有一个空格;

函数声明和定义中的所有形参必须有命名且一致;

所有形参应尽可能对齐;

缺省缩进为 2 个空格;

换行后的参数保持 4 个空格的缩进;

如果有些参数没有用到, 在函数定义处将参数名注释起来:

// 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*/) {}

Warning

.. code-block:: c++

// Bad - if someone wants to implement later, it's not clear what the // variable means. void Circle::Rotate(double) {}

8.5. Lambda 表达式

Tip

其它函数怎么格式化形参和函数体，Lambda 表达式就怎么格式化；捕获列表同理。

若用引用捕获，在变量名和 & 之间不留空格。

int x = 0;
auto add_to_x = [&x](int n) { x += n; };

短 lambda 就写得和内联函数一样。

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.6. 函数调用

Tip

要么一行写完函数调用，要么在圆括号里对参数分行，要么参数另起一行且缩进四格。如果没有其它顾虑的话，尽可能精简行数，比如把多个参数适当地放在同一行里。

函数调用遵循如下形式：

bool retval = DoSomething(argument1, argument2, argument3);

如果同一行放不下，可断为多行，后面每一行都和第一个实参对齐，左圆括号后和右圆括号前不要留空格：

bool retval = DoSomething(averyveryveryverylongargument1,
                          argument2, argument3);

参数也可以放在次行，缩进四格：

if (...) {
  ...
  ...
  if (...) {
    DoSomething(
        argument1, argument2,  // 4 space indent
        argument3, argument4);
  }

把多个参数放在同一行，是为了减少函数调用所需的行数，除非影响到可读性。有人认为把每个参数都独立成行，不仅更好读，而且方便编辑参数。不过，比起所谓的参数编辑，我们更看重可读性，且后者比较好办：

如果一些参数本身就是略复杂的表达式，且降低了可读性。那么可以直接创建临时变量描述该表达式，并传递给函数：

int my_heuristic = scores[x] * y + bases[x];
bool retval = DoSomething(my_heuristic, x, y, z);

或者放着不管，补充上注释：

bool retval = DoSomething(scores[x] * y + bases[x],  // Score heuristic.
                          x, y, z);

如果某参数独立成行，对可读性更有帮助的话，就这么办。

此外，如果一系列参数本身就有一定的结构，可以酌情地按其结构来决定参数格式：

// Transform the widget by a 3x3 matrix.
my_widget.Transform(x1, x2, x3,
                    y1, y2, y3,
                    z1, z2, z3);

8.7. 列表初始化格式

Tip

您平时怎么格式化函数调用，就怎么格式化列表初始化。

如果列表初始化伴随着名字，比如类型或变量名，您可以当名字是函数、{} 是函数调用的括号来格式化它。反之，就当它有个长度为零的名字。

// 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.8. 条件语句

Tip

倾向于不在圆括号内使用空格. 关键字 if 和 else 另起一行.

对基本条件语句有两种可以接受的格式. 一种在圆括号和条件之间有空格, 另一种没有.

最常见的是没有空格的格式. 哪种都可以, 但 保持一致性. 如果你是在修改一个文件, 参考当前已有格式. 如果是写新的代码, 参考目录下或项目中其它文件. 还在徘徊的话, 就不要加空格了.

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 和左圆括号间都有个空格. 右圆括号和左大括号之间也要有个空格:

Warning

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 分支则不允许:

Warning

// 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.
}

但如果语句中某个 if-else 分支使用了大括号的话, 其它分支也必须使用:

Warning

// 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;
}

8.9. 循环和开关选择语句

Tip

switch 语句可以使用大括号分段，以表明 cases 之间不是连在一起的。在单语句循环里，括号可用可不用。空循环体应使用 {} 或 continue.

switch 语句中的 case 块可以使用大括号也可以不用, 取决于你的个人喜好. 如果用的话, 要按照下文所述的方法.

如果有不满足 case 条件的枚举值, switch 应该总是包含一个 default 匹配 (如果有输入值没有 case 去处理, 编译器将报警). 如果 default 应该永远执行不到, 简单的加条 assert:

switch (var) {
  case 0: {  // 2 space indent
    ...      // 4 space indent
    break;
  }
  case 1: {
    ...
    break;
  }
  default: {
    assert(false);
  }
}

在单语句循环里，括号可用可不用：

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, 而不是一个简单的分号.

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

while (condition);  // Bad - looks like part of do/while loop.

8.10. 指针和引用表达式

Tip

句点或箭头前后不要有空格. 指针/地址操作符 (*, &) 之后不能有空格.

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

x = *p;
p = &x;
x = r.y;
x = r->y;

注意:啊

在访问成员时, 句点或箭头前后没有空格.
指针操作符 * 或 & 后没有空格.

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

// 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

char * c;  // Bad - spaces on both sides of *
const string & str;  // Bad - spaces on both sides of &

在单个文件内要保持风格一致, 所以, 如果是修改现有文件, 要遵照该文件的风格.

8.11. 布尔表达式

Tip

如果一个布尔表达式超过 标准行宽 <line-length>, 断行方式要统一一下.

下例中, 逻辑与 (&&) 操作符总位于行尾:

if (this_one_thing > this_other_thing &&
    a_third_thing == a_fourth_thing &&
    yet_another & last_one) {
  ...
}

注意, 上例的逻辑与 (&&) 操作符均位于行尾. 这格式在 Google 里很常见，您要把所有操作符放在开头也可以。可以考虑额外插入圆括号, 合理使用的话对增强可读性是很有帮助的. 此外直接用符号形式的操作符，比如 && 和 ~, 不要用词语形式的 and 和 compl.

8.12. 函数返回值

Tip

return 表达式里时没必要都用圆括号。

在 return expr; 里就用圆括号，当且只当您会在 x = epr; 用上它们（acgtyrant 注：字面上的意思就是这样，我也不知怎么理解，只能直译了；我猜意为「当且只当您用该函数的返回值赋值给某变量」）。

函数返回时不要使用圆括号:

return result;                  // No parentheses in the simple case.
// Parentheses OK to make a complex expression more readable.
return (some_long_condition &&
        another_condition);

Warning

return (value);                // You wouldn't write var = (value);
return(result);                // return is not a function!

8.13. 变量及数组初始化

Tip

用 =, () 和 {} 均可.

您可以用 =, () 和 {}, 以下都对：

int x = 3;
int x(3);
int x{3};
string name("Some Name");
string name = "Some Name";
string name{"Some Name"};

请务必小心列表初始化 {...} 用 std::initializer_list 构造函数初始化出的类型。非空列表初始化就会优先调用 std::initializer_list, 不过空列表初始化除外，后者原则上会调用默认构造函数。为了强制禁用 std::initializer_list 构造函数，请改用括号。

vector<int> v(100, 1);  // A vector of 100 1s.
vector<int> v{100, 1};  // A vector of 100, 1.

此外，列表初始化不允许整型类型的四舍五入，这可以用来避免一些类型上的编程失误。

int pi(3.14);  // OK -- pi == 3.
int pi{3.14};  // Compile error: narrowing conversion.

8.14. 预处理指令

Tip

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

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

// Good - directives at beginning of line
  if (lopsided_score) {
#if DISASTER_PENDING      // Correct -- Starts at beginning of line
    DropEverything();
#endif
    BackToNormal();
  }

Warning

// 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();
  }

8.15. 类格式

Tip

访问控制块的声明依次序是 public:, protected:, private:, 每次缩进 1 个空格.

类声明 (对类注释不了解的话, 参考 类注释 <class-comments>) 的基本格式如下:

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);
};

注意事项:

所有基类名应在 80 列限制下尽量与子类名放在同一行.

关键词 public:, protected:, private: 要缩进 1 个空格.

除第一个关键词 (一般是 public) 外, 其他关键词前要空一行. 如果类比较小的话也可以不空.

这些关键词后不要保留空行.

public 放在最前面, 然后是 protected, 最后是 private.

关于声明顺序的规则请参考 声明顺序 <declaration-order> 一节.

8.16. 初始化列表

Tip

构造函数初始化列表放在同一行或按四格缩进并排几行.

下面两种初始化列表方式都可以接受:

// 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();
  ...
}

8.17. 名字空间格式化

Tip

名字空间内容不缩进.

名字空间 <namespaces> 不要增加额外的缩进层次, 例如:

namespace {

void foo() {  // Correct.  No extra indentation within namespace.
  ...
}

}  // namespace

不要缩进名字空间:

Warning

namespace {

  // Wrong.  Indented when it should not be.
  void foo() {
    ...
  }

}  // namespace

声明嵌套命名空间时，每命名空间都独立成行。

namespace foo {
namespace bar {

8.18. 水平留白

Tip

水平留白的使用因地制宜. 永远不要在行尾添加没意义的留白.

常规:

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.
  ...
添加冗余的留白会给其他人编辑时造成额外负担. 因此, 行尾不要留空格. 如果确定一行代码已经修改完毕, 将多余的空格去掉; 或者在专门清理空格时去掉（确信没有其他人在处理). (yospaly 注: 现在大部分代码编辑器稍加设置后, 都支持自动删除行首/行尾空格, 如果不支持, 考虑换一款编辑器或 IDE)

循环和条件语句:

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
if ( test ) {     // parentheses, but this is rare.  Be consistent.
for ( int i = 0; i < 5; ++i ) {
for ( ; i < 5 ; ++i) {  // For loops always have a space after the
  ...                   // semicolon, and may have a space before the
                        // semicolon.
switch (i) {
  case 1:         // No space before colon in a switch case.
    ...
  case 2: break;  // Use a space after a colon if there's code after it.

操作符:

// Assignment operators always have spaces around them.
x = 0;

// Other binary operators usually have spaces around them, but it's
// OK to remove spaces around factors.  Parentheses should have no
// internal padding.
v = w * x + y / z;
v = w*x + y/z;
v = w * (x + z);

// No spaces separating unary operators and their arguments.
x = -5;
++x;
if (x && !y)
  ...

模板和转换:

// No spaces inside the angle brackets (< and >), before
// <, or between >( in a cast
vector<string> x;
y = static_cast<char*>(x);

// Spaces between type and pointer are OK, but be consistent.
vector<char *> x;
set<list<string>> x;        // Permitted in C++11 code.
set<list<string> > x;       // C++03 required a space in > >.

// You may optionally use symmetric spacing in < <.
set< list<string> > x;

8.19. 垂直留白

Tip

垂直留白越少越好.

这不仅仅是规则而是原则问题了: 不在万不得已, 不要使用空行. 尤其是: 两个函数定义之间的空行不要超过 2 行, 函数体首尾不要留空行, 函数体中也不要随意添加空行.

基本原则是: 同一屏可以显示的代码越多, 越容易理解程序的控制流. 当然, 过于密集的代码块和过于疏松的代码块同样难看, 取决于你的判断. 但通常是垂直留白越少越好.

空行心得如下：

函数体内开头或结尾的空行可读性微乎其微。
在多重 if-else 块里加空行或许有点可读性。

译者 (YuleFox) 笔记

对于代码格式, 因人, 系统而异各有优缺点, 但同一个项目中遵循同一标准还是有必要的;
行宽原则上不超过 80 列, 把 22 寸的显示屏都占完, 怎么也说不过去;
尽量不使用非 ASCII 字符, 如果使用的话, 参考 UTF-8 格式 (尤其是 UNIX/Linux 下, Windows 下可以考虑宽字符), 尽量不将字符串常量耦合到代码中, 比如独立出资源文件, 这不仅仅是风格问题了;
UNIX/Linux 下无条件使用空格, MSVC 的话使用 Tab 也无可厚非;
函数参数, 逻辑条件, 初始化列表: 要么所有参数和函数名放在同一行, 要么所有参数并排分行;
除函数定义的左大括号可以置于行首外, 包括函数/类/结构体/枚举声明, 各种语句的左大括号置于行尾, 所有右大括号独立成行;
./-> 操作符前后不留空格, */& 不要前后都留, 一个就可, 靠左靠右依各人喜好;
预处理指令/命名空间不使用额外缩进, 类/结构体/枚举/函数/语句使用缩进;
初始化用 = 还是 () 依个人喜好, 统一就好;
return 不要加 ();
水平/垂直留白不要滥用, 怎么易读怎么来.
关于 UNIX/Linux 风格为什么要把左大括号置于行尾 (.cc 文件的函数实现处, 左大括号位于行首), 我的理解是代码看上去比较简约, 想想行首除了函数体被一对大括号封在一起之外, 只有右大括号的代码看上去确实也舒服; Windows 风格将左大括号置于行首的优点是匹配情况一目了然.

译者（acgtyrant）笔记：

80 行限制事实上有助于避免代码可读性失控，比如超多重嵌套块，超多重函数调用等等。
Linux 上设置好了 Locale 就几乎一劳永逸设置好所有开发环境的编码，不像奇葩的 Windows.
Google 强调有一对 if-else 时，不论有没有嵌套，都要有大括号。Apple 正好有栽过跟头.
其实我主张指针／地址操作符与变量名紧邻，int* a, b vs int *a, b, 新手会误以为前者的 b 是 int * 变量，但后者就不一样了，高下立判。
在这风格指南里我才刚知道 C++ 原来还有所谓的 Alternative operator representations, 大概没人用吧。
事实上，如果您熟悉英语本身的书写规则，就会发现该风格指南在格式上的规定与英语语法相当一脉相承。比如普通标点符号和单词后面还有文本的话，总会留一个空格；特殊符号与单词之间就不用留了，比如 if (true) 中的圆括号与 true.

30 KiB Raw Blame History Unescape Escape

8. 格式

8.1. 行长度

8.2. 非 ASCII 字符

8.3. 空格还是制表位

8.4. 函数声明与定义

8.5. Lambda 表达式

8.6. 函数调用

8.7. 列表初始化格式

8.8. 条件语句

8.9. 循环和开关选择语句

8.10. 指针和引用表达式

8.11. 布尔表达式

8.12. 函数返回值

8.13. 变量及数组初始化

8.14. 预处理指令

8.15. 类格式

8.16. 初始化列表

8.17. 名字空间格式化

8.18. 水平留白

8.19. 垂直留白

译者 (YuleFox) 笔记

译者（acgtyrant）笔记：

30 KiB

Raw Blame History