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

yulefox 64306bc234 upload google-cpp-styleguide

2012-07-17 12:47:54 +08:00

24 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 编码标记)

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 个空格的缩进;

如果函数声明成 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*/) {}

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

Tip

尽量放在同一行, 否则, 将实参封装在圆括号中.

函数调用遵循如下形式:

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

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

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

如果函数参数很多, 出于可读性的考虑可以在每行只放一个参数:

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

如果函数名非常长, 以至于超过 行最大长度 <line-length>, 可以将所有参数独立成行:

if (...) {
  ...
  ...
  if (...) {
    DoSomethingThatRequiresALongFunctionName(
        very_long_argument1,  // 4 space indent
        argument2,
        argument3,
        argument4);
  }

8.6. 条件语句

Tip

倾向于不在圆括号内使用空格. 关键字 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

.. code-block:: c++

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

.. code-block:: c++

// 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.7. 循环和开关选择语句

Tip

switch 语句可以使用大括号分段. 空循环体应使用 {} 或 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);
  }
}

空循环体应使用 {} 或 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

.. code-block:: c++

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

8.8. 指针和引用表达式

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

.. code-block:: c++

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

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

8.9. 布尔表达式

Tip

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

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

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

注意, 上例的逻辑与 (&&) 操作符均位于行尾. 可以考虑额外插入圆括号, 合理使用的话对增强可读性是很有帮助的.

8.10. 函数返回值

Tip

return 表达式中不要用圆括号包围.

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

return x;  // not return(x);

8.11. 变量及数组初始化

Tip

用 = 或 () 均可.

在二者中做出选择; 下面的方式都是正确的:

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

8.12. 预处理指令

Tip

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

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

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

Warning

.. code-block:: c++

// 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.13. 类格式

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.14. 初始化列表

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.15. 名字空间格式化

Tip

名字空间内容不缩进.

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

namespace {

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

}  // namespace

不要缩进名字空间:

Warning

.. code-block:: c++

namespace {

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

} // namespace

8.16. 水平留白

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.

操作符:

x = 0;              // Assignment operators always have spaces around
                    // them.
x = -5;             // No spaces separating unary operators and their
++x;                // arguments.
if (x && !y)
  ...
v = w * x + y / z;  // Binary operators usually 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.

模板和转换:

vector<string> x;           // No spaces inside the angle
y = static_cast<char*>(x);  // brackets (< and >), before
                            // <, or between >( in a cast.
vector<char *> x;           // Spaces between type and pointer are
                            // okay, but be consistent.
set<list<string> > x;       // C++ requires a space in > >.
set< list<string> > x;      // You may optionally make use
                            // symmetric spacing in < <.

8.17. 垂直留白

Tip

垂直留白越少越好.

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

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

Warning

函数首尾不要有空行

void Function() {

  // Unnecessary blank lines before and after

}

Warning

代码块首尾不要有空行

while (condition) {
  // Unnecessary blank line after

}
if (condition) {

  // Unnecessary blank line before
}

if-else 块之间空一行是可以接受的:

if (condition) {
  // Some lines of code too small to move to another function,
  // followed by a blank line.

} else {
  // Another block of code
}

译者 (YuleFox) 笔记

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

24 KiB Raw Blame History

8. 格式

8.1. 行长度

8.2. 非 ASCII 字符

8.3. 空格还是制表位

8.4. 函数声明与定义

8.5. 函数调用

8.6. 条件语句

8.7. 循环和开关选择语句

8.8. 指针和引用表达式

8.9. 布尔表达式

8.10. 函数返回值

8.11. 变量及数组初始化

8.12. 预处理指令

8.13. 类格式

8.14. 初始化列表

8.15. 名字空间格式化

8.16. 水平留白

8.17. 垂直留白

译者 (YuleFox) 笔记

24 KiB

Raw Blame History