Ling.Li: 1. Finish modifying Chapter 3.

google-cpp-styleguide/classes.rst

@@ -6,390 +6,350 @@
 3.1. 构造函数的职责
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+**总述**
 
-    不要在构造函数中进行复杂的初始化 (尤其是那些有可能失败或者需要调用虚函数的初始化).
+不要在构造函数中调用虚函数, 也不要在无法报出错误时进行可能失败的初始化.
 
-定义:
+**定义**
 
-    在构造函数体中进行初始化操作.
+在构造函数中可以进行各种初始化操作.
 
-优点:
+**优点**
 
-    排版方便, 无需担心类是否已经初始化.
+- 无需考虑类是否被初始化.
 
-缺点:
+- 经过构造函数完全初始化后的对象可以为 ``const`` 类型, 也能更方便地被标准容器或算法使用.
 
-    在构造函数中执行操作引起的问题有:
+**缺点**
 
-        - 构造函数中很难上报错误, `不能使用异常 <#...>`_.
-        
-        - 操作失败会造成对象初始化失败，进入不确定状态.
-        
-        - 如果在构造函数内调用了自身的虚函数, 这类调用是不会重定向到子类的虚函数实现. 即使当前没有子类化实现, 将来仍是隐患.
-        
-        - 如果有人创建该类型的全局变量 (虽然违背了上节提到的规则), 构造函数将先 ``main()`` 一步被调用, 有可能破坏构造函数中暗含的假设条件. 例如, `gflags <http://code.google.com/p/google-gflags/>`_ 尚未初始化.
+- 如果在构造函数内调用了自身的虚函数, 这类调用是不会重定向到子类的虚函数实现. 即使当前没有子类化实现, 将来仍是隐患.
 
-结论:
+- 在没有使程序崩溃 (因为并不是一个始终合适的方法) 或者使用异常 (因为已经被 :ref:`禁用 <exceptions>` 了) 等方法的条件下, 构造函数很难上报错误
 
-    构造函数不得调用虚函数, 或尝试报告一个非致命错误. 如果对象需要进行有意义的 (non-trivial) 初始化, 考虑使用明确的 Init() 方法或使用工厂模式.
+- 如果执行失败, 会得到一个初始化失败的对象, 这个对象有可能进入不正常的状态, 必须使用 ``bool isValid()`` 或类似这样的机制才能检查出来, 然而这是一个十分容易被疏忽的方法.
 
-3.2. 初始化
+- 构造函数的地址是无法被取得的, 因此, 举例来说, 由构造函数完成的工作是无法以简单的方式交给其他线程的.
+
+**结论**
+
+构造函数不允许调用虚函数. 如果代码允许, 直接终止程序是一个合适的处理错误的方式. 否则, 考虑用 ``Init()`` 方法或工厂函数.
+
+构造函数不得调用虚函数, 或尝试报告一个非致命错误. 如果对象需要进行有意义的 (non-trivial) 初始化, 考虑使用明确的 Init() 方法或使用工厂模式. Avoid ``Init()`` methods on objects with no other states that affect which public methods may be called (此类形式的半构造对象有时无法正确工作).
+
+.. _implicit-conversions:
+
+3.2. 隐式类型转换
 ~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+**总述**
 
-    如果类中定义了成员变量, 则必须在类中为每个类提供初始化函数或定义一个构造函数. 若未声明构造函数, 则编译器会生成一个默认的构造函数, 这有可能导致某些成员未被初始化或被初始化为不恰当的值.
+不要定义隐式类型转换. 对于转换运算符和单参数构造函数, 请使用 ``explicit`` 关键字.
 
-定义:
+**定义**
 
-    ``new`` 一个不带参数的类对象时, 会调用这个类的默认构造函数. 用 ``new[]`` 创建数组时, 默认构造函数则总是被调用. 在类成员里面进行初始化是指声明一个成员变量的时候使用一个结构例如 ``int _count = 17`` 或者 ``string _name{"abc"}`` 来替代 ``int _count`` 或者 ``string _name`` 这样的形式.
+隐式类型转换允许一个某种类型 (称作 *源类型*) 的对象被用于需要另一种类型 (称作 *目的类型*) 的位置, 例如, 将一个 ``int`` 类型的参数传递给需要 ``double`` 类型的函数.
 
-优点:
+除了语言所定义的隐式类型转换, 用户还可以通过在类定义中添加合适的成员定义自己需要的转换. 在源类型中定义隐式类型转换, 可以通过目的类型名的类型转换运算符实现 (例如 ``operator bool()``). 在目的类型中定义隐式类型转换, 则通过以源类型作为其唯一参数 (或唯一无默认值的参数) 的构造函数实现.
 
-    用户定义的默认构造函数将在没有提供初始化操作时将对象初始化. 这样就保证了对象在被构造之时就处于一个有效且可用的状态, 同时保证了对象在被创建时就处于一个显然"不可能"的状态, 以此帮助调试.
+``explicit`` 关键字可以用于构造函数或 (在 C++11 引入) 类型转换运算符, 以保证只有当目的类型在调用点被显式写明时才能进行类型转换, 例如使用 ``cast``. 这不仅作用于隐式类型转换, 还能作用于 C++11 的列表初始化语法:
 
-缺点:
+.. code-block:: c++
 
-    对代码编写者来说, 这是多余的工作.
-    
-    如果一个成员变量在声明时初始化又在构造函数中初始化, 有可能造成混乱, 因为构造函数中的值会覆盖掉声明中的值.
+    class Foo {
+      explicit Foo(int x, double y);
+      ...
+    };
 
-结论:
+    void Func(Foo f);
 
-    简单的初始化用类成员初始化完成, 尤其是当一个成员变量要在多个构造函数里用相同的方式初始化的时候.
+此时下面的代码是不允许的:
 
-    如果你的类中有成员变量没有在类里面进行初始化, 而且没有提供其它构造函数, 你必须定义一个 (不带参数的) 默认构造函数. 把对象的内部状态初始化成一致 / 有效的值无疑是更合理的方式.
-    
-	这么做的原因是: 如果你没有提供其它构造函数, 又没有定义默认构造函数, 编译器将为你自动生成一个. 编译器生成的构造函数并不会对对象进行合理的初始化.
-	
-	如果你定义的类继承现有类, 而你又没有增加新的成员变量, 则不需要为新类定义默认构造函数.
+.. code-block:: c++
 
-3.3. 显式构造函数
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Func({42, 3.14});  // Error
 
-.. tip::
-    对单个参数的构造函数使用 C++ 关键字 ``explicit``.
+这一代码从技术上说并非隐式类型转换, 但是语言标准认为这是 ``explicit`` 应当限制的行为.
 
-定义:
+**优点**
 
-    通常, 如果构造函数只有一个参数, 可看成是一种隐式转换. 打个比方, 如果你定义了 ``Foo::Foo(string name)``, 接着把一个字符串传给一个以 ``Foo`` 对象为参数的函数, 构造函数 ``Foo::Foo(string name)`` 将被调用, 并将该字符串转换为一个 ``Foo`` 的临时对象传给调用函数. 看上去很方便, 但如果你并不希望如此通过转换生成一个新对象的话, 麻烦也随之而来. 为避免构造函数被调用造成隐式转换, 可以将其声明为 ``explicit``.
-    
-    除单参数构造函数外, 这一规则也适用于除第一个参数以外的其他参数都具有默认参数的构造函数, 例如 Foo::Foo(string name, int id = 42).
+- 有时目的类型名是一目了然的, 通过避免显式地写出类型名, 隐式类型转换可以让一个类型的可用性和表达性更强.
 
-优点:
+- 隐式类型转换可以简单地取代函数重载.
 
-    避免不合时宜的变换.
+- 在初始化对象时, 列表初始化语法是一种简洁明了的写法.
 
-缺点:
+**缺点**
 
-    无
+- 隐式类型转换会隐藏类型不匹配的错误. 有时, 目的类型并不符合用户的期望, 甚至用户根本没有意识到发生了类型转换.
 
-结论:
+- 隐式类型转换会让代码难以阅读, 尤其是在有函数重载的时候, 因为这时很难判断到底是哪个函数被调用.
 
-    所有单参数构造函数都必须是显式的. 在类定义中, 将关键字 ``explicit`` 加到单参数构造函数前: ``explicit Foo(string name);``
+- 单参数构造函数有可能会被无意地用作隐式类型转换.
 
-    例外: 在极少数情况下, 拷贝构造函数可以不声明成 ``explicit``. 作为其它类的透明包装器的类也是特例之一. 类似的例外情况应在注释中明确说明.
-    
-    最后, 只有 std::initializer_list 的构造函数可以是非 explicit, 以允许你的类型结构可以使用列表初始化的方式进行赋值. 例如:
-    
-        .. code-block:: c++
-        
-            MyType m = {1, 2};
-            MyType MakeMyType() { return {1, 2}; }
-            TakeMyType({1, 2});	
+- 如果单参数构造函数没有加上 ``explicit`` 关键字, 读者无法判断这一函数究竟是要作为隐式类型转换, 还是作者忘了加上 ``explicit`` 标记.
 
-.. _copy-constructors:
+- 并没有明确的方法用来判断哪个类应该提供类型转换, 这会使得代码变得含糊不清.
 
-3.4. 可拷贝类型和可移动类型
+- 如果目的类型是隐式指定的, 那么列表初始化会出现和隐式类型转换一样的问题, 尤其是在列表中只有一个元素的时候.
+
+**结论**
+
+在类型定义中, 类型转换运算符和单参数构造函数都应当用 ``explicit`` 进行标记. 一个例外是, 拷贝和移动构造函数不应当被标记为 ``explicit``, 因为它们并不执行类型转换. 对于设计目的就是用于对其他类型进行透明包装的类来说, 隐式类型转换有时是必要且合适的. 这时应当联系项目组长并说明特殊情况.
+
+不能以一个参数进行调用的构造函数不应当加上 ``explicit``. 接受一个 ``std::initializer_list`` 作为参数的构造函数也应当省略 ``explicit``, 以便支持拷贝初始化 (例如 ``MyType m = {1, 2};).
+
+.. _copyable-and-movable-types:
+
+3.3. 可拷贝类型和可移动类型
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+**总述**
 
-    如果你的类型需要, 就让它们支持拷贝 / 移动. 否则, 就把隐式产生的拷贝和移动函数禁用.
+如果你的类型需要, 就让它们支持拷贝 / 移动. 否则, 就把隐式产生的拷贝和移动函数禁用.
 
-定义:
+**定义**
 
-    可拷贝类型允许对象在初始化时得到来自相同类型的另一对象的值, 或在赋值时被赋予相同类型的另一对象的值, 同时不改变源对象的值. 对于用户定义的类型, 拷贝操作一般通过拷贝构造函数与拷贝赋值操作符定义. string 类型就是一个可拷贝类型的例子.
-    
-	可移动类型允许对象在初始化时得到来自相同类型的临时对象的值, 或在赋值时被赋予相同类型的临时对象的值 (因此所有可拷贝对象也是可移动的). std::unique_ptr<int> 就是一个可移动但不可复制的对象的例子. 对于用户定义的类型, 移动操作一般是通过移动构造函数和移动赋值操作符实现的.
-	
-	拷贝 / 移动构造函数在某些情况下会被编译器隐式调用. 例如, 通过传值的方式传递对象.
+可拷贝类型允许对象在初始化时得到来自相同类型的另一对象的值, 或在赋值时被赋予相同类型的另一对象的值, 同时不改变源对象的值. 对于用户定义的类型, 拷贝操作一般通过拷贝构造函数与拷贝赋值操作符定义. ``string`` 类型就是一个可拷贝类型的例子.
 
-优点:
+可移动类型允许对象在初始化时得到来自相同类型的临时对象的值, 或在赋值时被赋予相同类型的临时对象的值 (因此所有可拷贝对象也是可移动的). ``std::unique_ptr<int>`` 就是一个可移动但不可复制的对象的例子. 对于用户定义的类型, 移动操作一般是通过移动构造函数和移动赋值操作符实现的.
 
-    可移动及可拷贝类型的对象可以通过传值的方式进行传递或者返回, 这使得 API 更简单, 更安全也更通用. 与传指针和引用不同, 这样的传递不会造成所有权, 生命周期, 可变性等方面的混乱, 也就没必要在协议中予以明确. 这同时也防止了客户端与实现在非作用域内的交互, 使得它们更容易被理解与维护. 这样的对象可以和需要传值操作的通用 API 一起使用, 例如大多数容器.
-    
-	拷贝 / 移动构造函数与赋值操作一般来说要比它们的各种替代方案, 比如 Clone(), CopyFrom() or Swap(), 更容易定义, 因为它们能通过编译器产生, 无论是隐式的还是通过 = 默认. 这种方式很简洁, 也保证所有数据成员都会被复制. 拷贝与移动构造函数一般也更高效, 因为它们不需要堆的分配或者是单独的初始化和赋值步骤, 同时, 对于类似省略不必要的拷贝这样的优化它们也更加合适.
-	
-	移动操作允许隐式且高效地将源数据转移出右值对象. 这有时能让代码风格更加清晰.
+拷贝 / 移动构造函数在某些情况下会被编译器隐式调用. 例如, 通过传值的方式传递对象.
 
-缺点:
+**优点**
 
-    许多类型都不需要拷贝, 为它们提供拷贝操作会让人迷惑, 也显得荒谬而不合理. 为基类提供拷贝 / 赋值操作是有害的, 因为在使用它们时会造成对象切割. 默认的或者随意的拷贝操作实现可能是不正确的, 这往往导致令人困惑并且难以诊断出的错误.
-    
-	拷贝构造函数是隐式调用的, 也就是说, 这些调用很容易被忽略. 这会让人迷惑, 尤其是对那些所用的语言约定或强制要求传引用的程序员来说更是如此. 同时, 这从一定程度上说会鼓励过度拷贝, 从而导致性能上的问题.
+可移动及可拷贝类型的对象可以通过传值的方式进行传递或者返回, 这使得 API 更简单, 更安全也更通用. 与传指针和引用不同, 这样的传递不会造成所有权, 生命周期, 可变性等方面的混乱, 也就没必要在协议中予以明确. 这同时也防止了客户端与实现在非作用域内的交互, 使得它们更容易被理解与维护. 这样的对象可以和需要传值操作的通用 API 一起使用, 例如大多数容器.
 
-结论:
+拷贝 / 移动构造函数与赋值操作一般来说要比它们的各种替代方案, 比如 ``Clone()``, ``CopyFrom()`` or ``Swap()``, 更容易定义, 因为它们能通过编译器产生, 无论是隐式的还是通过 ``= default``. 这种方式很简洁, 也保证所有数据成员都会被复制. 拷贝与移动构造函数一般也更高效, 因为它们不需要堆的分配或者是单独的初始化和赋值步骤, 同时, 对于类似 `省略不必要的拷贝 <http://en.cppreference.com/w/cpp/language/copy_elision>`_ 这样的优化它们也更加合适.
 
-    如果需要就让你的类型可拷贝 / 可移动. 作为一个经验法则, 如果对于你的用户来说这个拷贝操作不是一眼就能看出来的, 那就不要把类型设置为可拷贝. 如果让类型可拷贝, 一定要同时给出拷贝构造函数和赋值操作的定义. 如果让类型可拷贝, 同时移动操作的效率高于拷贝操作, 那么就把移动的两个操作 (移动构造函数和赋值操作) 也给出定义. 如果类型不可拷贝, 但是移动操作的正确性对用户显然可见, 那么把这个类型设置为只可移动并定义移动的两个操作.
-    
-	建议通过 ``= default`` 定义拷贝和移动操作. 定义非默认的移动操作目前需要异常. 时刻记得检测默认操作的正确性.
-	由于存在对象切割的风险, 不要为任何有可能有派生类的对象提供赋值操作或者拷贝 / 移动构造函数 (当然也不要继承有这样的成员函数的类). 如果你的基类需要可复制属性, 请提供一个 ``public virtual Clone()`` 和一个 ``protected`` 的拷贝构造函数以供派生类实现.
-	
-	如果你的类不需要拷贝 / 移动操作, 请显式地通过 ``= delete`` 或其他手段禁用之.
+移动操作允许隐式且高效地将源数据转移出右值对象. 这有时能让代码风格更加清晰.
 
-3.5. 委派和继承构造函数
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**缺点**
 
-.. tip::
+许多类型都不需要拷贝, 为它们提供拷贝操作会让人迷惑, 也显得荒谬而不合理. 单件类型 (``Registerer``), 与特定的作用域相关的类型 (``Cleanup``), 与其他对象实体紧耦合的类型 (``Mutex``) 从逻辑上来说都不应该提供拷贝操作. 为基类提供拷贝 / 赋值操作是有害的, 因为在使用它们时会造成 `对象切割 <https://en.wikipedia.org/wiki/Object_slicing>`_ . 默认的或者随意的拷贝操作实现可能是不正确的, 这往往导致令人困惑并且难以诊断出的错误.
 
-    在能够减少重复代码的情况下使用委派和继承构造函数.
-    
-定义:
+拷贝构造函数是隐式调用的, 也就是说, 这些调用很容易被忽略. 这会让人迷惑, 尤其是对那些所用的语言约定或强制要求传引用的程序员来说更是如此. 同时, 这从一定程度上说会鼓励过度拷贝, 从而导致性能上的问题.
 
-    委派和继承构造函数是由 C++11 引进为了减少构造函数重复代码而开发的两种不同的特性. 通过特殊的初始化列表语法, 委派构造函数允许类的一个构造函数调用其他的构造函数. 例如:
-    
-        .. code-block:: c++
-        
-            X::X(const string& name) : name_(name) {
-              ...
-            }
-            
-            X::X() : X("") { }
+**结论**
 
-	继承构造函数允许派生类直接调用基类的构造函数, 一如继承基类的其他成员函数, 而无需重新声明. 当基类拥有多个构造函数时这一功能尤其有用. 例如:
-	
-        .. code-block:: c++
-        
-            class Base {
-             public:
-              Base();
-              Base(int n);
-              Base(const string& s);
-              ...
-            };
-            
-            class Derived : public Base {
-             public:
-              using Base::Base;  // Base's constructors are redeclared here.
-            };
+如果需要就让你的类型可拷贝 / 可移动. 作为一个经验法则, 如果对于你的用户来说这个拷贝操作不是一眼就能看出来的, 那就不要把类型设置为可拷贝. 如果让类型可拷贝, 一定要同时给出拷贝构造函数和赋值操作的定义, 反之亦然. 如果让类型可拷贝, 同时移动操作的效率高于拷贝操作, 那么就把移动的两个操作 (移动构造函数和赋值操作) 也给出定义. 如果类型不可拷贝, 但是移动操作的正确性对用户显然可见, 那么把这个类型设置为只可移动并定义移动的两个操作.
 
-    如果派生类的构造函数只是调用基类的构造函数而没有其他行为时, 这一功能特别有用.
-    
-优点:
+如果定义了拷贝/移动操作, 则要保证这些操作的默认实现是正确的. 记得时刻检查默认操作的正确性, 并且在文档中说明类是可拷贝的且/或可移动的.
 
-	委派和继承构造函数可以减少冗余代码, 提高可读性.
-	委派构造函数对 Java 程序员来说并不陌生.
-	
-缺点:
+.. code-block:: c++
 
-	使用辅助函数可以预估出委派构造函数的行为.
-	如果派生类和基类相比引入了新的成员变量, 继承构造函数就会让人迷惑, 因为基类并不知道这些新的成员变量的存在.
-	
-结论:
-	
-	只在能够减少冗余代码, 提高可读性的前提下使用委派和继承构造函数. 如果派生类有新的成员变量, 那么使用继承构造函数时要小心. 如果在派生类中对成员变量使用了类内部初始化的话, 继承构造函数还是适用的.
+    class Foo {
+     public:
+      Foo(Foo&& other) : field_(other.field) {}
+      // 差, 只定义了移动构造函数, 而没有定义对应的赋值运算符.
+
+     private:
+      Field field_;
+    };
+
+由于存在对象切割的风险, 不要为任何有可能有派生类的对象提供赋值操作或者拷贝 / 移动构造函数 (当然也不要继承有这样的成员函数的类). 如果你的基类需要可复制属性, 请提供一个 ``public virtual Clone()`` 和一个 ``protected`` 的拷贝构造函数以供派生类实现.
+
+如果你的类不需要拷贝 / 移动操作, 请显式地通过在 ``public`` 域中使用 ``= delete`` 或其他手段禁用之.
+
+.. code-block:: c++
+
+    // MyClass is neither copyable nor movable.
+    MyClass(const MyClass&) = delete;
+    MyClass& operator=(const MyClass&) = delete;
 
 .. _structs-vs-classes:
 
-3.6. 结构体 VS. 类
+3.4. 结构体 VS. 类
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+**总述**
 
-	仅当只有数据时使用 struct, 其它一概使用 class.
+仅当只有数据成员时使用 ``struct``, 其它一概使用 ``class``.
 
-说明:
+**说明**
 
-	在 C++ 中 struct 和 class 关键字几乎含义一样. 我们为这两个关键字添加我们自己的语义理解, 以便未定义的数据类型选择合适的关键字.
-	
-	struct 用来定义包含数据的被动式对象, 也可以包含相关的常量, 但除了存取数据成员之外, 没有别的函数功能. 并且存取功能是通过直接访问位域, 而非函数调用. 除了构造函数, 析构函数, Initialize(), Reset(), Validate() 等类似的函数外, 不能提供其它功能的函数.
-	
-	如果需要更多的函数功能, class 更适合. 如果拿不准, 就用 class.
-	
-	为了和 STL 保持一致, 对于仿函数和 trait 特性可以不用 class 而是使用 struct.
-	
-	注意: 类和结构体的成员变量使用不同的命名规则.
+在 C++ 中 ``struct`` 和 ``class`` 关键字几乎含义一样. 我们为这两个关键字添加我们自己的语义理解, 以便为定义的数据类型选择合适的关键字.
+
+``struct`` 用来定义包含数据的被动式对象, 也可以包含相关的常量, 但除了存取数据成员之外, 没有别的函数功能. 并且存取功能是通过直接访问位域, 而非函数调用. 除了构造函数, 析构函数, ``Initialize()``, ``Reset()``, ``Validate()`` 等类似的用于设定数据成员的函数外, 不能提供其它功能的函数.
+
+如果需要更多的函数功能, ``class`` 更适合. 如果拿不准, 就用 ``class``.
+
+为了和 STL 保持一致, 对于仿函数等特性可以不用 ``class`` 而是使用 ``struct``.
+
+注意: 类和结构体的成员变量使用不同的 :ref:`命名规则 <variable-names>`.
 
 .. _inheritance:
 
-3.7. 继承
+3.5. 继承
 ~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+**总述**
 
-    使用组合 (composition, YuleFox 注: 这一点也是 GoF 在 <<Design Patterns>> 里反复强调的) 常常比使用继承更合理. 如果使用继承的话, 定义为 ``public`` 继承.
+使用组合 (YuleFox 注: 这一点也是 GoF 在 <<Design Patterns>> 里反复强调的) 常常比使用继承更合理. 如果使用继承的话, 定义为 ``public`` 继承.
 
-定义:
+**定义**
 
-    当子类继承基类时, 子类包含了父基类所有数据及操作的定义. C++ 实践中, 继承主要用于两种场合: 实现继承 (implementation inheritance), 子类继承父类的实现代码; 接口继承 (interface inheritance), 子类仅继承父类的方法名称.
+当子类继承基类时, 子类包含了父基类所有数据及操作的定义. C++ 实践中, 继承主要用于两种场合: 实现继承, 子类继承父类的实现代码; :ref:`<接口继承 interface>`, 子类仅继承父类的方法名称.
 
-优点:
+**优点**
 
-    实现继承通过原封不动的复用基类代码减少了代码量. 由于继承是在编译时声明, 程序员和编译器都可以理解相应操作并发现错误. 从编程角度而言, 接口继承是用来强制类输出特定的 API. 在类没有实现 API 中某个必须的方法时, 编译器同样会发现并报告错误.
+实现继承通过原封不动的复用基类代码减少了代码量. 由于继承是在编译时声明, 程序员和编译器都可以理解相应操作并发现错误. 从编程角度而言, 接口继承是用来强制类输出特定的 API. 在类没有实现 API 中某个必须的方法时, 编译器同样会发现并报告错误.
 
-缺点:
+**缺点**
 
-    对于实现继承, 由于子类的实现代码散布在父类和子类间之间, 要理解其实现变得更加困难. 子类不能重写父类的非虚函数, 当然也就不能修改其实现. 基类也可能定义了一些数据成员, 还要区分基类的实际布局.
+对于实现继承, 由于子类的实现代码散布在父类和子类间之间, 要理解其实现变得更加困难. 子类不能重写父类的非虚函数, 当然也就不能修改其实现. 基类也可能定义了一些数据成员, 因此还必须区分基类的实际布局.
 
-结论:
+**结论**
 
-    所有继承必须是 ``public`` 的. 如果你想使用私有继承, 你应该替换成把基类的实例作为成员对象的方式.
+所有继承必须是 ``public`` 的. 如果你想使用私有继承, 你应该替换成把基类的实例作为成员对象的方式.
 
-    不要过度使用实现继承. 组合常常更合适一些. 尽量做到只在 "是一个" ("is-a", YuleFox 注: 其他 "has-a" 情况下请使用组合) 的情况下使用继承: 如果 ``Bar`` 的确 "是一种" Foo, ``Bar`` 才能继承 ``Foo``.
+不要过度使用实现继承. 组合常常更合适一些. 尽量做到只在 "是一个" ("is-a", YuleFox 注: 其他 "has-a" 情况下请使用组合) 的情况下使用继承: 如果 ``Bar`` 的确 "是一种" ``Foo``, ``Bar`` 才能继承 ``Foo``.
 
-    必要的话, 析构函数声明为 ``virtual``. 如果你的类有虚函数, 则析构函数也应该为虚函数. 注意 `数据成员在任何情况下都必须是私有的 <....>`_.
+必要的话, 析构函数声明为 ``virtual``. 如果你的类有虚函数, 则析构函数也应该为虚函数.
 
-    当重载一个虚函数, 在衍生类中把它明确的声明为 ``virtual``. 理论依据: 如果省略 ``virtual`` 关键字, 代码阅读者不得不检查所有父类, 以判断该函数是否是虚函数.
+对于可能被子类访问的成员函数, 不要过度使用 ``protected`` 关键字. 注意, 数据成员都必须是 :ref:`私有的 <access-control>`.
+
+对于重载的虚函数或虚析构函数, 使用 ``override``, 或 (较不常用的) ``final`` 关键字显式地进行标记. 较早 (早于 C++11) 的代码可能会使用 ``virtual`` 关键字作为不得已的选项. 因此, 在声明重载时, 请使用 ``override``, ``final`` 或 ``virtual`` 的其中之一进行标记. 标记为 ``override`` 或 ``final`` 的析构函数如果不是对基类虚函数的重载的话, 编译会报错, 这有助于捕获常见的错误. 这些标记起到了文档的作用, 因为如果省略这些关键字, 代码阅读者不得不检查所有父类, 以判断该函数是否是虚函数.
 
 .. _multiple-inheritance:
 
-3.8. 多重继承
+3.6. 多重继承
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+**总述**
 
-    真正需要用到多重实现继承的情况少之又少. 只在以下情况我们才允许多重继承: 最多只有一个基类是非抽象类; 其它基类都是以 ``Interface`` 为后缀的 :ref:`纯接口类 <interface>`.
+真正需要用到多重实现继承的情况少之又少. 只在以下情况我们才允许多重继承: 最多只有一个基类是非抽象类; 其它基类都是以 ``Interface`` 为后缀的 :ref:`纯接口类 <interface>`.
 
-定义:
+**定义**
 
-    多重继承允许子类拥有多个基类. 要将作为 *纯接口* 的基类和具有 *实现* 的基类区别开来.
+多重继承允许子类拥有多个基类. 要将作为 *纯接口* 的基类和具有 *实现* 的基类区别开来.
 
-优点:
+**优点**
 
-    相比单继承 (见 :ref:`继承 <inheritance>`), 多重实现继承可以复用更多的代码.
+相比单继承 (见 :ref:`继承 <inheritance>`), 多重实现继承可以复用更多的代码.
 
-缺点:
+**缺点**
 
-    真正需要用到多重 *实现* 继承的情况少之又少. 多重实现继承看上去是不错的解决方案, 但你通常也可以找到一个更明确, 更清晰的不同解决方案.
+真正需要用到多重 *实现* 继承的情况少之又少. 有时多重实现继承看上去是不错的解决方案, 但这时你通常也可以找到一个更明确, 更清晰的不同解决方案.
 
-结论:
+**结论**
 
-    只有当所有父类除第一个外都是 :ref:`纯接口类 <interface>` 时, 才允许使用多重继承. 为确保它们是纯接口, 这些类必须以 ``Interface`` 为后缀.
+只有当所有父类除第一个外都是 :ref:`纯接口类 <interface>` 时, 才允许使用多重继承. 为确保它们是纯接口, 这些类必须以 ``Interface`` 为后缀.
 
-.. note::
+**注意**
 
-    关于该规则, Windows 下有个 :ref:`特例 <windows-code>`.
+关于该规则, Windows 下有个 :ref:`特例 <windows-code>`.
 
 .. _interface:
 
-3.9. 接口
+3.7. 接口
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+**总述**
 
-    接口是指满足特定条件的类, 这些类以 ``Interface`` 为后缀 (不强制).
+接口是指满足特定条件的类, 这些类以 ``Interface`` 为后缀 (不强制).
 
-定义:
+**定义**
 
-    当一个类满足以下要求时, 称之为纯接口:
+当一个类满足以下要求时, 称之为纯接口:
 
-        - 只有纯虚函数 ("``=0``") 和静态函数 (除了下文提到的析构函数).
-        - 没有非静态数据成员.
-        - 没有定义任何构造函数. 如果有, 也不能带有参数, 并且必须为 ``protected``.
-        - 如果它是一个子类, 也只能从满足上述条件并以 ``Interface`` 为后缀的类继承.
+- 只有纯虚函数 ("``=0``") 和静态函数 (除了下文提到的析构函数).
 
-    接口类不能被直接实例化, 因为它声明了纯虚函数. 为确保接口类的所有实现可被正确销毁, 必须为之声明虚析构函数 (作为上述第 1 条规则的特例, 析构函数不能是纯虚函数). 具体细节可参考 Stroustrup 的 *The C++ Programming Language, 3rd edition* 第 12.4 节.
+- 没有非静态数据成员.
 
-优点:
+- 没有定义任何构造函数. 如果有, 也不能带有参数, 并且必须为 ``protected``.
 
-    以 ``Interface`` 为后缀可以提醒其他人不要为该接口类增加函数实现或非静态数据成员. 这一点对于 :ref:`多重继承 <multiple-inheritance>` 尤其重要. 另外, 对于 Java 程序员来说, 接口的概念已是深入人心.
+- 如果它是一个子类, 也只能从满足上述条件并以 ``Interface`` 为后缀的类继承.
 
-缺点:
+接口类不能被直接实例化, 因为它声明了纯虚函数. 为确保接口类的所有实现可被正确销毁, 必须为之声明虚析构函数 (作为上述第 1 条规则的特例, 析构函数不能是纯虚函数). 具体细节可参考 Stroustrup 的 *The C++ Programming Language, 3rd edition* 第 12.4 节.
 
-    ``Interface`` 后缀增加了类名长度, 为阅读和理解带来不便. 同时，接口特性作为实现细节不应暴露给用户.
+**优点**
 
-结论:
+以 ``Interface`` 为后缀可以提醒其他人不要为该接口类增加函数实现或非静态数据成员. 这一点对于 :ref:`多重继承 <multiple-inheritance>` 尤其重要. 另外, 对于 Java 程序员来说, 接口的概念已是深入人心.
 
-    只有在满足上述需要时, 类才以 ``Interface`` 结尾, 但反过来, 满足上述需要的类未必一定以 ``Interface`` 结尾.
+**缺点**
 
-3.10. 运算符重载
+``Interface`` 后缀增加了类名长度, 为阅读和理解带来不便. 同时, 接口属性作为实现细节不应暴露给用户.
+
+**结论**
+
+只有在满足上述条件时, 类才以 ``Interface`` 结尾, 但反过来, 满足上述需要的类未必一定以 ``Interface`` 结尾.
+
+3.8. 运算符重载
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+**总述**
 
-    除少数特定环境外，不要重载运算符.
+除少数特定环境外, 不要重载运算符. 也不要创建用户定义字面量.
 
-定义:
+**定义**
 
-    一个类可以定义诸如 ``+`` 和 ``/`` 等运算符, 使其可以像内建类型一样直接操作.
+C++ 允许用户通过使用 ``operator`` 关键字 `对内建运算符进行重载定义 <http://en.cppreference.com/w/cpp/language/operators>`_ , 只要其中一个参数是用户定义的类型. ``operator`` 关键字还允许用户使用 ``operator""`` 定义新的字面运算符, 并且定义类型转换函数, 例如 ``operator bool()``.
 
-优点:
+**优点**
 
-    使代码看上去更加直观, 类表现的和内建类型 (如 ``int``) 行为一致. 重载运算符使 ``Equals()``, ``Add()`` 等函数名黯然失色. 为了使一些模板函数正确工作, 你可能必须定义操作符.
+重载运算符可以让代码更简洁易懂, 也使得用户定义的类型和内建类型拥有相似的行为. 重载运算符对于某些运算来说是符合符合语言习惯的名称 (例如 ``==``, ``<``, ``=``, ``<<``), 遵循这些语言约定可以让用户定义的类型更易读, 也能更好地和需要这些重载运算符的函数库进行交互操作.
 
-缺点:
+对于创建用户定义的类型的对象来说, 用户定义字面量是一种非常简洁的标记.
 
-    虽然操作符重载令代码更加直观, 但也有一些不足:
+**缺点**
 
-    - 混淆视听, 让你误以为一些耗时的操作和操作内建类型一样轻巧.
-    - 更难定位重载运算符的调用点, 查找 ``Equals()`` 显然比对应的 ``==`` 调用点要容易的多.
-    - 有的运算符可以对指针进行操作, 容易导致 bug. ``Foo + 4`` 做的是一件事, 而 ``&Foo + 4`` 可能做的是完全不同的另一件事. 对于二者, 编译器都不会报错, 使其很难调试;
+- 要提供正确, 一致, 不出现异常行为的操作符运算需要花费不少精力, 而且如果达不到这些要求的话, 会导致令人迷惑的 Bug.
 
-    重载还有令你吃惊的副作用. 比如, 重载了 ``operator&`` 的类不能被前置声明.
+- 过度使用运算符会带来难以理解的代码, 尤其是在重载的操作符的语义与通常的约定不符合时.
 
-结论:
+- 函数重载有多少弊端, 运算符重载就至少有多少.
 
-    一般不要重载运算符. 尤其是赋值操作 (``operator=``) 比较诡异, 应避免重载. 如果需要的话, 可以定义类似 ``Equals()``, ``CopyFrom()`` 等函数.
+- 运算符重载会混淆视听, 让你误以为一些耗时的操作和操作内建类型一样轻巧.
 
-    然而, 极少数情况下可能需要重载运算符以便与模板或 "标准" C++ 类互操作 (如 ``operator<<(ostream&, const T&)``). 只有被证明是完全合理的才能重载, 但你还是要尽可能避免这样做. 尤其是不要仅仅为了在 STL 容器中用作键值就重载 ``operator==`` 或 ``operator<``; 相反, 你应该在声明容器的时候, 创建相等判断和大小比较的仿函数类型.
+- 对重载运算符的调用点的查找需要的可就不仅仅是像 grep 那样的程序了, 这时需要能够理解 C++ 语法的搜索工具.
 
-    有些 STL 算法确实需要重载 ``operator==`` 时, 你可以这么做, 记得别忘了在文档中说明原因.
+- 如果重载运算符的参数写错, 此时得到的可能是一个完全不同的重载而非编译错误. 例如: ``foo < bar`` 执行的是一个行为, 而 ``&foo < &bar`` 执行的就是完全不同的另一个行为了.
 
-    参考 :ref:`拷贝构造函数 <copy-constructors>` 和 :ref:`函数重载 <function-overloading>`.
+- 重载某些运算符本身就是有害的. 例如, 重载一元运算符 ``&`` 会导致同样的代码有完全不同的含义, 这取决于重载的声明对某段代码而言是否是可见的. 重载诸如 ``&&``, ``||`` 和 ``,`` 会导致运算顺序和内建运算的顺序不一致.
 
-3.11. 存取控制
+- 运算符从通常定义在类的外部, 所以对于同一运算, 可能出现不同的文件引入了不同的定义的风险. 如果两种定义都链接到同一二进制文件, 就会导致未定义的行为, 有可能表现为难以发现的运行时错误.
+
+- 用户定义字面量所创建的语义形式对于某些有经验的 C++ 程序员来说都是很陌生的.
+
+**结论**
+
+只有在意义明显, 不会出现奇怪的行为并且与对应的内建运算符的行为一致时才定义重载运算符. 例如, ``|`` 要作为位或或逻辑或来使用, 而不是作为 shell 中的管道.
+
+只有对用户自己定义的类型重载运算符. 更准确地说, 将它们和它们所操作的类型定义在同一个头文件中, ``.cc`` 中和命名空间中. 这样做无论类型在哪里都能够使用定义的运算符, 并且最大程度上避免了多重定义的风险. 如果可能的话, 请避免将运算符定义为模板, 因为此时它们必须对任何模板参数都能够作用. 如果你定义了一个运算符, 请将其相关且有意义的运算符都进行定义, 并且保证这些定义的语义是一致的. 例如, 如果你重载了 ``<``, 那么请将所有的比较运算符都进行重载, 并且保证对于同一组参数, ``<`` 和 ``>`` 不会同时返回 ``true``.
+
+建议不要将不进行修改的二元运算符定义为成员函数. 如果一个二元运算符被定义为类成员, 这时隐式转换会作用域右侧的参数却不会作用于左侧. 这时会出现 ``a < b`` 能够通过编译而 ``b < a`` 不能的情况, 这是很让人迷惑的.
+
+不要为了避免重载操作符而走极端. 比如说, 应当定义 ``==``, ``=``, 和 ``<<`` 而不是 ``Equals()``, ``CopyFrom()`` 和 ``PrintTo()``. 反过来说, 不要只是为了满足函数库需要而去定义运算符重载. 比如说, 如果你的类型没有自然顺序, 而你要将它们存入 ``std::set`` 中, 最好还是定义一个自定义的比较运算符而不是重载 ``<``.
+
+不要重载 ``&&``, ``||``, ``,`` 或一元运算符 ``&``. 不要重载 ``operator""``, 也就是说, 不要引入用户定义字面量.
+
+类型转换运算符在 :ref:`隐式类型转换 <implicit-conversions>` 一节有提及. ``=`` 运算符在 :ref:`可拷贝类型和可移动类型 <copyable-and-movable-types>` 一节有提及. 运算符 ``<<`` 在 :ref:`流 <streams>` 一节有提及. 同时请参见 :ref:`函数重载 <function-overloading>` 一节, 其中提到的的规则对运算符重载同样适用.
+
+.. _access-control:
+
+3.9. 存取控制
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+**总述**
 
-    将 *所有* 数据成员声明为 ``private``, 并根据需要提供相应的存取函数. 例如, 某个名为 ``foo_`` 的变量, 其取值函数是 ``foo()``. 还可能需要一个赋值函数 ``set_foo()``.
-    
-    特例是, 静态常量数据成员 (一般写做 kFoo) 不需要是私有成员.
-
-    一般在头文件中把存取函数定义成内联函数.
-
-    参考 :ref:`继承 <inheritance>` 和 :ref:`函数命名 <function-names>`
+将 *所有* 数据成员声明为 ``private``, 除非是 ``static const`` 类型成员 (遵循 :ref:`常量命名规则 <constant-names>`). 处于技术上的原因, 在使用 `Google Test <https://github.com/google/googletest>`_ 时我们允许测试固件类中的数据成员为 ``protected``.
 
 .. _declaration-order:
 
-3.11. 声明顺序
+3.10. 声明顺序
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+**总述**
 
-    在类中使用特定的声明顺序: ``public:`` 在 ``private:`` 之前, 成员函数在数据成员 (变量) 前;
+将相似的声明放在一起, 将 ``public`` 部分放在最前.
 
-类的访问控制区段的声明顺序依次为: ``public:``, ``protected:``, ``private:``. 如果某区段没内容, 可以不声明.
+**说明**
 
-每个区段内的声明通常按以下顺序:
+类定义一般应以 ``public:`` 开始, 后跟 ``protected:``, 最后是 ``private:``. 省略空部分.
 
-    - ``typedefs`` 和枚举
-    - 常量
-    - 构造函数
-    - 析构函数
-    - 成员函数, 含静态成员函数
-    - 数据成员, 含静态数据成员
+在各个部分中, 建议将类似的声明放在一起, 并且建议以如下的顺序: 类型 (包括 ``typedef``, ``using`` 和嵌套的结构体与类), 常量, 工厂函数, 构造函数, 赋值运算符, 析构函数, 其它函数, 数据成员.
 
-友元声明应该放在 private 区段. 如果用宏 DISALLOW_COPY_AND_ASSIGN 禁用拷贝和赋值, 应当将其置于 private 区段的末尾, 也即整个类声明的末尾. 参见可拷贝类型和可移动类型.
-
-``.cc`` 文件中函数的定义应尽可能和声明顺序一致.
-
-不要在类定义中内联大型函数. 通常, 只有那些没有特别意义或性能要求高, 并且是比较短小的函数才能被定义为内联函数. 更多细节参考 :ref:`内联函数 <inline-functions>`.
-
-3.12. 编写简短函数
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. tip::
-
-    倾向编写简短, 凝练的函数.
-
-我们承认长函数有时是合理的, 因此并不硬性限制函数的长度. 如果函数超过 40 行, 可以思索一下能不能在不影响程序结构的前提下对其进行分割.
-
-即使一个长函数现在工作的非常好, 一旦有人对其修改, 有可能出现新的问题. 甚至导致难以发现的 bug. 使函数尽量简短, 便于他人阅读和修改代码.
-
-在处理代码时, 你可能会发现复杂的长函数. 不要害怕修改现有代码: 如果证实这些代码使用 / 调试困难, 或者你需要使用其中的一小段代码, 考虑将其分割为更加简短并易于管理的若干函数.
+不要将大段的函数定义内联在类定义中. 只有那些普通的, 或非性能关键且短小的函数可以内联在函数定义中. 参见 :ref:`内联函数 <inline-functions>` 一节.
 
 译者 (YuleFox) 笔记
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -401,7 +361,7 @@
 #. 仅在作为数据集合时使用 ``struct``;
 #. 组合 > 实现继承 > 接口继承 > 私有继承, 子类重载的虚函数也要声明 ``virtual`` 关键字, 虽然编译器允许不这样做;
 #. 避免使用多重继承, 使用时, 除一个基类含有实现外, 其他基类均为纯接口;
-#. 接口类类名以 ``Interface`` 为后缀, 除提供带实现的虚析构函数, 静态成员函数外, 其他均为纯虚函数, 不定义非静态数据成员, 不提供构造函数, 提供的话，声明为 ``protected``;
+#. 接口类类名以 ``Interface`` 为后缀, 除提供带实现的虚析构函数, 静态成员函数外, 其他均为纯虚函数, 不定义非静态数据成员, 不提供构造函数, 提供的话, 声明为 ``protected``;
 #. 为降低复杂性, 尽量不重载操作符, 模板, 标准类中使用时提供文档说明;
 #. 存取函数一般内联在头文件中;
 #. 声明次序: ``public`` -> ``protected`` -> ``private``;

google-cpp-styleguide/others.rst

@@ -162,6 +162,8 @@
 
 友元扩大了 (但没有打破) 类的封装边界. 某些情况下, 相对于将类成员声明为 ``public``, 使用友元是更好的选择, 尤其是如果你只允许另一个类访问该类的私有成员时. 当然, 大多数类都只应该通过其提供的公有成员进行互操作.
 
+.. _exceptions:
+
 5.7. 异常
 ~~~~~~~~~~~~~~~~
 
@@ -297,6 +299,8 @@
 
     至于 ``dynamic_cast`` 参见 :ref:`RTTI`.
 
+.. _streams:
+
 5.10. 流
 ~~~~~~~~~~~~~~