编程风格指南

about develop my think other things 2009-07-21 arnehuo 手机阅读

原文是Google C++编程风格指南，主要选取命名规范的部分，其他中文内容请看http://www.cppblog.com/Fox/

原文地址：Google C++ Style Guide

命名约定

最重要的一致性规则是命名管理，命名风格直接可以直接确定命名实体是：类型、变量、函数、常量、宏等等，无需查找实体声明，我们大脑中的模式匹配引擎依赖于这些命名规则。

命名规则具有一定随意性，但相比按个人喜好命名，一致性更重要，所以不管你怎么想，规则总归是规则。

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

// enums
enum UrlTableErrors { ...

4. 变量命名（Variable Names）

变量名一律小写，单词间以下划线相连，类的成员变量以下划线结尾，如my_exciting_local_variable、my_exciting_member_variable_。

普通变量命名：

举例：

string table_name;  // OK - uses underscore.
string tablename;   // OK - all lowercase.

string tableName;   // Bad - mixed case.

类数据成员：

结构体的数据成员可以和普通变量一样，不用像类那样接下划线：

struct UrlTableProperties {
  string name;
  int num_entries;
}

结构体与类的讨论参考第三篇结构体vs.类一节。

全局变量：

对全局变量没有特别要求，少用就好，可以以g_或其他易与局部变量区分的标志为前缀。

5. 常量命名（Constant Names）

在名称前加k：kDaysInAWeek。

所有编译时常量（无论是局部的、全局的还是类中的）和其他变量保持些许区别，k后接大写字母开头的单词：

const int kDaysInAWeek = 7;

6. 函数命名（Function Names）

普通函数（regular functions，译者注，这里与访问函数等特殊函数相对）大小写混合，存取函数（accessors and mutators）则要求与变量名匹配：MyExcitingFunction()、MyExcitingMethod()、my_exciting_member_variable()、set_my_exciting_member_variable()。

普通函数：

函数名以大写字母开头，每个单词首字母大写，没有下划线：

AddTableEntry()
DeleteUrl()

存取函数：

存取函数要与存取的变量名匹配，这儿摘录一个拥有实例变量num_entries_的类：

class MyClass {
 public:
  ...
  int num_entries() const { return num_entries_; }
  void set_num_entries(int num_entries) { num_entries_ = num_entries; }

 private:
  int num_entries_;
};

其他短小的内联函数名也可以使用小写字母，例如，在循环中调用这样的函数甚至都不需要缓存其值，小写命名就可以接受。

译者注：从这一点上可以看出，小写的函数名意味着可以直接内联使用。

7. 命名空间（Namespace Names）

命名空间的名称是全小写的，其命名基于项目名称和目录结构：google_awesome_project。

关于命名空间的讨论和如何命名，参考第二篇命名空间。

8. 枚举命名（Enumerator Names）

枚举值应全部大写，单词间以下划线相连：MY_EXCITING_ENUM_VALUE。

枚举名称属于类型，因此大小写混合：UrlTableErrors。

enum UrlTableErrors {
  OK = 0,
  ERROR_OUT_OF_MEMORY,
  ERROR_MALFORMED_INPUT,
};

9. 宏命名（Macro Names）

你并不打算使用宏，对吧？如果使用，像这样：MY_MACRO_THAT_SCARES_SMALL_CHILDREN。

参考第四篇预处理宏，通常是不使用宏的，如果绝对要用，其命名像枚举命名一样全部大写、使用下划线：

#define ROUND(x) ...
#define PI_ROUNDED 3.0
MY_EXCITING_ENUM_VALUE

10. 命名规则例外（Exceptions to Naming Rules）

当命名与现有C/C++实体相似的对象时，可参考现有命名约定：

bigopen(): 函数名，参考open()
uint: typedef类型定义
bigpos: struct或class，参考pos
sparse_hash_map: STL相似实体；参考STL命名约定
LONGLONG_MAX: 常量，类似INT_MAX

______________________________________

译者：命名约定就相对轻松许多，在遵从代码一致性、可读性的前提下，略显随意：

1. 总体规则：不要随意缩写，如果说ChangeLocalValue写作ChgLocVal还有情可原的话，把ModifyPlayerName写作MdfPlyNm就太过分了，除函数名可适当为动词外，其他命名尽量使用清晰易懂的名词；

2. 宏、枚举等使用全部大写+下划线；

3. 变量（含类、结构体成员变量）、文件、命名空间、存取函数等使用全部小写+下划线，类成员变量以下划线结尾，全局变量以g_开头；

4. 普通函数、类型（含类与结构体、枚举类型）、常量等使用大小写混合，不含下划线；

5. 参考现有或相近命名约定。

注释

注释虽然写起来很痛苦，但对保证代码可读性至为重要，下面的规则描述了应该注释什么、注释在哪儿。当然也要记住，注释的确很重要，但最好的代码本身就是文档（self-documenting），类型和变量命名意义明确要比通过注释解释模糊的命名好得多。

注释是为别人（下一个需要理解你的代码的人）而写的，认真点吧，那下一个人可能就是你！

1. 注释风格（Comment Style）

使用//或/* */，统一就好。

//或/* */都可以，//只是用的更加广泛，在如何注释和注释风格上确保统一。

2. 文件注释（File Comments）

在每一个文件开头加入版权公告，然后是文件内容描述。

法律公告和作者信息：

每一文件包含以下项，依次是：

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

如果你觉得已经在文件顶部详细描述了该类，想直接简单的来上一句“完整描述见文件顶部”的话，还是多少在类中加点注释吧。

如果类有任何同步前提（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”，因为已经暗含其中了：

// 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.
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,
                                  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. 注释要言简意赅，不要拖沓冗余，复杂的东西简单化和简单的东西复杂化都是要被鄙视的；

4. 对于Chinese coders来说，用英文注释还是用中文注释，it is a problem，但不管怎样，注释是为了让别人看懂，难道是为了炫耀编程语言之外的你的母语或外语水平吗；

5. 注释不要太乱，适当的缩进才会让人乐意看，但也没有必要规定注释从第几列开始（我自己写代码的时候总喜欢这样），UNIX/LINUX下还可以约定是使用tab还是space，个人倾向于space；

6. TODO很不错，有时候，注释确实是为了标记一些未完成的或完成的不尽如人意的地方，这样一搜索，就知道还有哪些活要干，日志都省了。

格式

代码风格和格式确实比较随意，但一个项目中所有人遵循同一风格是非常容易的，作为个人未必同意下述格式规则的每一处，但整个项目服从统一的编程风格是很重要的，这样做才能让所有人在阅读和理解代码时更加容易。

1. 行长度（Line Length）

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

我们也认识到这条规则是存有争议的，但如此多的代码都遵照这一规则，我们感觉一致性更重要。

优点：提倡该原则的人认为强迫他们调整编辑器窗口大小很野蛮。很多人同时并排开几个窗口，根本没有多余空间拓宽某个窗口，人们将窗口最大尺寸加以限定，一致使用80列宽，为什么要改变呢？

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

结论：80个字符是最大值。例外：

1) 如果一行注释包含了超过80字符的命令或URL，出于复制粘贴的方便可以超过80字符；

2) 包含长路径的可以超出80列，尽量避免；

3) 头文件保护（防止重复包含第一篇）可以无视该原则。

2. 非ASCII字符（Non-ASCII Characters）

尽量不使用非ASCII字符，使用时必须使用UTF-8格式。

哪怕是英文，也不应将用户界面的文本硬编码到源代码中，因此非ASCII字符要少用。特殊情况下可以适当包含此类字符，如，代码分析外部数据文件时，可以适当硬编码数据文件中作为分隔符的非ASCII字符串；更常用的是（不需要本地化的）单元测试代码可能包含非ASCII字符串。此类情况下，应使用UTF- 8格式，因为很多工具都可以理解和处理其编码，十六进制编码也可以，尤其是在增强可读性的情况下——如"\xEF\xBB\xBF"是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）总是和函数名在同一行；

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

// 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另起一行。

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

最常见的是没有空格的格式，那种都可以，还是一致性为主。如果你是在修改一个文件，参考当前已有格式；如果是写新的代码，参考目录下或项目中其他文件的格式，还在徘徊的话，就不要加空格了。

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

但如果语句中哪一分支使用了大括号的话，其他部分也必须使用：

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

空循环体应使用{}或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字符），如果断行要统一一下。

下例中，逻辑与（&&）操作符总位于行尾：

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
    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列限制下尽量与子类名放在同一行；

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

不要缩进：

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

17. 垂直留白（Vertical Whitespace）

垂直留白越少越好。

这不仅仅是规则而是原则问题了：不是非常有必要的话就不要使用空行。尤其是：不要在两个函数定义之间空超过2行，函数体头、尾不要有空行，函数体中也不要随意添加空行。

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

函数头、尾不要有空行：

void Function() {

  // Unnecessary blank lines before and after

}

代码块头、尾不要有空行：

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
}

______________________________________

译者：首先说明，对于代码格式，因人、因系统各有优缺点，但同一个项目中遵循同一标准还是有必要的：

1. 行宽原则上不超过80列，把22寸的显示屏都占完，怎么也说不过去；

2. 尽量不使用非ASCII字符，如果使用的话，参考UTF-8格式（尤其是UNIX/Linux下，Windows下可以考虑宽字符），尽量不将字符串常量耦合到代码中，比如独立出资源文件，这不仅仅是风格问题了；

3. UNIX/Linux下无条件使用空格，MSVC的话使用Tab也无可厚非；

4. 函数参数、逻辑条件、初始化列表：要么所有参数和函数名放在同一行，要么所有参数并排分行；

5. 除函数定义的左大括号可以置于行首外，包括函数/类/结构体/枚举声明、各种语句的左大括号置于行尾，所有右大括号独立成行；

6. ./->操作符前后不留空格，*/&不要前后都留，一个就可，靠左靠右依各人喜好；

7. 预处理指令/命名空间不使用额外缩进，类/结构体/枚举/函数/语句使用缩进；

8. 初始化用=还是()依个人喜好，统一就好；

9. return不要加()；

10. 水平/垂直留白不要滥用，怎么易读怎么来。

规则之例外

前面说明的编码习惯基本是强制性的，但所有优秀的规则都允许例外。

1. 现有不统一代码（Existing Non-conformant Code）

对于现有不符合既定编程风格的代码可以网开一面。

当你修改使用其他风格的代码时，为了与代码原有风格保持一致可以不使用本指南约定。如果不放心可以与代码原作者或现在的负责人员商讨，记住，一致性包括原有的一致性。

1. Windows代码（Windows Code）

Windows程序员有自己的编码习惯，主要源于Windows的一些头文件和其他Microsoft代码。我们希望任何人都可以顺利读懂你的代码，所以针对所有平台的C++编码给出一个单独的指导方案。

如果你一直使用Windows编码风格的，这儿有必要重申一下某些你可能会忘记的指南（译者注，我怎么感觉像在被洗脑:D）：

1) 不要使用匈牙利命名法（Hungarian notation，如定义整型变量为iNum），使用Google命名约定，包括对源文件使用.cc扩展名；

2) Windows定义了很多原有内建类型的同义词（译者注，这一点，我也很反感），如DWORD、HANDLE等等，在调用Windows API时这是完全可以接受甚至鼓励的，但还是尽量使用原来的C++类型，例如，使用const TCHAR *而不是LPCTSTR；

3) 使用Microsoft Visual C++进行编译时，将警告级别设置为3或更高，并将所有warnings当作errors处理；

4) 不要使用#pragma once;作为包含保护，使用C++标准包含保护，包含保护的文件路径包含到项目树顶层（译者注，#include<prj_name/public/tools.h>）；

5) 除非万不得已，否则不使用任何不标准的扩展，如#pragma和__declspec，允许使用__declspec(dllimport)和__declspec(dllexport)，但必须通过DLLIMPORT和DLLEXPORT等宏，以便其他人在共享使用这些代码时容易放弃这些扩展。

在Windows上，只有很少一些偶尔可以不遵守的规则：

1) 通常我们禁止使用多重继承，但在使用COM和ATL/WTL类时可以使用多重继承，为了执行COM或ATL/WTL类及其接口时可以使用多重实现继承；

2) 虽然代码中不应使用异常，但在ATL和部分STL（包括Visual C++的STL）中异常被广泛使用，使用ATL时，应定义_ATL_NO_EXCEPTIONS以屏蔽异常，你要研究一下是否也屏蔽掉STL的异常，如果不屏蔽，开启编译器异常也可以，注意这只是为了编译STL，自己仍然不要写含异常处理的代码；

3) 通常每个项目的每个源文件中都包含一个名为StdAfx.h或precompile.h的头文件方便头文件预编译，为了使代码方便与其他项目共享，避免显式包含此文件（precompile.cc除外），使用编译器选项/FI以自动包含；

4) 通常名为resource.h、且只包含宏的资源头文件，不必拘泥于此风格指南。

团队合作

参考常识，保持一致。

编辑代码时，花点时间看看项目中的其他代码并确定其风格，如果其他代码if语句中使用空格，那么你也要使用。如果其中的注释用星号（*）围成一个盒子状，你也这样做：

/**********************************
* Some comments are here.
* There may be many lines.
**********************************/

编程风格指南的使用要点在于提供一个公共的编码规范，所有人可以把精力集中在实现内容而不是表现形式上。我们给出了全局的风格规范，但局部的风格也很重要，如果你在一个文件中新加的代码和原有代码风格相去甚远的话，这就破坏了文件本身的整体美观也影响阅读，所以要尽量避免。

好了，关于编码风格写的差不多了，代码本身才是更有趣的，尽情享受吧！

Benjy Weinberger
Craig Silverstein
Gregory Eitzmann
Mark Mentovai
Tashana Landray