diff --git a/google-cpp-styleguide/scoping.rst b/google-cpp-styleguide/scoping.rst index 5143e60..2912243 100644 --- a/google-cpp-styleguide/scoping.rst +++ b/google-cpp-styleguide/scoping.rst @@ -8,7 +8,7 @@ .. tip:: - 鼓励在 ``.cc`` 文件内使用匿名命名空间. 使用具名的命名空间时, 其名称可基于项目名或相对路径. 禁止使用 using 指示（using-directive）。禁止使用内联命名空间（inline namespace）。 + 鼓励在 ``.cc`` 文件内使用匿名命名空间或 ``static`` 声明. 使用具名的命名空间时, 其名称可基于项目名或相对路径. 禁止使用 using 指示（using-directive）。禁止使用内联命名空间（inline namespace）。 **定义:** @@ -34,9 +34,11 @@ **缺点:** - 命名空间具有迷惑性, 因为它们和类一样提供了额外的 (可嵌套的) 命名轴线. + 命名空间具有迷惑性, 因为它们使得区分两个相同命名所指代的定义更加困难。 - 命名空间很容易令人迷惑，毕竟它们不再受其声明所在命名空间的限制。内联命名空间只在大型版本控制里有用。 + 内联命名空间很容易令人迷惑，毕竟其内部的成员不再受其声明所在命名空间的限制。内联命名空间只在大型版本控制里有用。 + + 有时候不得不多次引用某个定义在许多嵌套命名空间里的实体，使用完整的命名空间会导致代码的冗长。 在头文件中使用匿名空间导致违背 C++ 的唯一定义原则 (One Definition Rule (ODR)). @@ -44,29 +46,9 @@ 根据下文将要提到的策略合理使用命名空间. -2.1.1. 匿名命名空间 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + - 遵守 `命名空间命名 `_ 中的规则。 -- 在 ``.cc`` 文件中, 允许甚至鼓励使用匿名命名空间, 以避免运行时的命名冲突: - - .. code-block:: c++ - - namespace { // .cc 文件中 - - // 命名空间的内容无需缩进 - enum { kUNUSED, kEOF, kERROR }; // 经常使用的符号 - bool AtEof() { return pos_ == kEOF; } // 使用本命名空间内的符号 EOF - - } // namespace - -然而, 与特定类关联的文件作用域声明在该类中被声明为类型, 静态数据成员或静态成员函数, 而不是匿名命名空间的成员. 如上例所示, 匿名空间结束时用注释 ``// namespace`` 标识. - -- 不要在 ``.h`` 文件中使用匿名命名空间. - -2.1.2. 具名的命名空间 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -具名的命名空间使用方式如下: + - 像之前的几个例子中一样，在命名空间的最后注释出命名空间的名字。 - 用命名空间把文件包含, `gflags `_ 的声明/定义, 以及类的前置声明以外的整个源文件封装起来, 以区别于其它命名空间: @@ -97,7 +79,7 @@ } // namespace mynamespace - 通常的 ``.cc`` 文件包含更多, 更复杂的细节, 比如引用其他命名空间的类等. + 更复杂的 ``.cc`` 文件包含更多, 更复杂的细节, 比如 gflags 或 using 声明。 .. code-block:: c++ @@ -105,97 +87,78 @@ DEFINE_FLAG(bool, someflag, false, "dummy flag"); - class C; // 全局命名空间中类 C 的前置声明 - namespace a { class A; } // a::A 的前置声明 - namespace a { ...code for a... // 左对齐 } // namespace a + - 不要在命名空间 ``std`` 内声明任何东西, 包括标准库的类前置声明. 在 ``std`` 命名空间声明实体是未定义的行为, 会导致如不可移植. 声明标准库下的实体, 需要包含对应的头文件. - - 不要在命名空间 ``std`` 内声明任何东西, 包括标准库的类前置声明. 在 ``std`` 命名空间声明实体会导致不确定的问题, 比如不可移植. 声明标准库下的实体, 需要包含对应的头文件. - - - 最好不要使用 using 指示，以保证命名空间下的所有名称都可以正常使用. + - 不应该使用 *using 指示* 引入整个命名空间的标识符号。 .. code-block:: c++ // 禁止 —— 污染命名空间 using namespace foo; - - 在 ``.cc`` 文件, ``.h`` 文件的函数, 方法或类中, 可以使用 using 声明。 + - 不要在头文件中使用 *命名空间别名* 除非显式标记内部命名空间使用。因为任何在头文件中引入的命名空间都会成为公开API的一部分。 .. code-block:: c++ - // 允许: .cc 文件中 - // .h 文件的话, 必须在函数, 方法或类的内部使用 - using ::foo::bar; - - - 在 ``.cc`` 文件, ``.h`` 文件的函数, 方法或类中, 允许使用命名空间别名. + // 在 .cc 中使用别名缩短常用的命名空间 + namespace baz = ::foo::bar::baz; .. code-block:: c++ - // 允许: .cc 文件中 - // .h 文件的话, 必须在函数, 方法或类的内部使用 - - namespace fbz = ::foo::bar::baz; - - // 在 .h 文件里 + // 在 .h 中使用别名缩短常用的命名空间 namespace librarian { - //以下别名在所有包含了该头文件的文件中生效。 + namespace impl { // 仅限内部使用 namespace sidetable = ::pipeline_diagnostics::sidetable; + } // namespace impl inline void my_inline_function() { - // namespace alias local to a function (or method). + // 限制在一个函数中的命名空间别名 namespace baz = ::foo::bar::baz; ... } } // namespace librarian - 注意在 .h 文件的别名对包含了该头文件的所有人可见，所以在公共头文件（在项目外可用）以及它们递归包含的其它头文件里，不要用别名。毕竟原则上公共 API 要尽可能地精简。 - - 禁止用内联命名空间 -2.2. 嵌套类 -~~~~~~~~~~~~~~~~~~ +.. _unnamed-namespace-and-static-variables: + +2.2. 匿名命名空间和静态变量 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tip:: - 当公有嵌套类作为接口的一部分时, 虽然可以直接将他们保持在全局作用域中, 但将嵌套类的声明置于 :ref:`namespaces` 内是更好的选择. + 在 ``.cc`` 文件中定义一个不需要被外部引用的变量时，可以将它们放在匿名命名空间或声明为 ``static`` 。但是不要在 ``.h`` 文件中这么做。 -定义: 在一个类内部定义另一个类; 嵌套类也被称为 *成员类 (member class)*. +**定义:** - .. code-block:: c++ - - class Foo { - - private: - // Bar是嵌套在Foo中的成员类 - class Bar { - ... - }; - - }; - -**优点:** - - 当嵌套 (或成员) 类只被外围类使用时非常有用; 把它作为外围类作用域内的成员, 而不是去污染外部作用域的同名类. 嵌套类可以在外围类中做前置声明, 然后在 ``.cc`` 文件中定义, 这样避免在外围类的声明中定义嵌套类, 因为嵌套类的定义通常只与实现相关. - -**缺点:** - - 嵌套类只能在外围类的内部做前置声明. 因此, 任何使用了 ``Foo::Bar*`` 指针的头文件不得不包含类 ``Foo`` 的整个声明. + 所有置于匿名命名空间的声明都具有内部链接性，函数和变量可以经由声明为 ``static`` 拥有内部链接性，这意味着你在这个文件中声明的这些标识符都不能在另一个文件中被访问。即使两个文件声明了完全一样名字的标识符，它们所指向的实体实际上是完全不同的。 **结论:** - 不要将嵌套类定义成公有, 除非它们是接口的一部分, 比如, 嵌套类含有某些方法的一组选项. + 推荐、鼓励在 ``.cc`` 中对于不需要在其他地方引用的标识符使用内部链接性声明，但是不要在 ``.h`` 中使用。 + + 匿名命名空间的声明和具名的格式相同，在最后注释上 ``namespace`` : + + .. code-block:: c++ + + namespace { + ... + } // namespace + +.. _nonmember-static-member-and-global-functions: 2.3. 非成员函数、静态成员函数和全局函数 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tip:: - 使用静态成员函数或命名空间内的非成员函数, 尽量不要用裸的全局函数. + 使用静态成员函数或命名空间内的非成员函数, 尽量不要用裸的全局函数. 将一系列函数直接置于命名空间中，不要用类的静态方法模拟出命名空间的效果，类的静态方法应当和类的实例或静态数据紧密相关. **优点:** @@ -207,12 +170,35 @@ **结论:** - 有时, 把函数的定义同类的实例脱钩是有益的, 甚至是必要的. 这样的函数可以被定义成静态成员, 或是非成员函数. 非成员函数不应依赖于外部变量, 应尽量置于某个命名空间内. 相比单纯为了封装若干不共享任何静态数据的静态成员函数而创建类, 不如使用 :ref:`namespaces` 。 + 有时, 把函数的定义同类的实例脱钩是有益的, 甚至是必要的. 这样的函数可以被定义成静态成员, 或是非成员函数. 非成员函数不应依赖于外部变量, 应尽量置于某个命名空间内. 相比单纯为了封装若干不共享任何静态数据的静态成员函数而创建类, 不如使用 :ref:`namespaces` 。举例而言，对于头文件 ``myproject/foo_bar.h`` , 应当使用 + + .. code-block:: c++ + + namespace myproject { + namespace foo_bar { + void Function1(); + void Function2(); + } // namespace foo_bar + } // namespace myproject + + 而非 + + .. code-block:: c++ + + namespace myproject { + class FooBar { + public: + static void Function1(); + static void Function2(); + }; + } // namespace myproject 定义在同一编译单元的函数, 被其他编译单元直接调用可能会引入不必要的耦合和链接时依赖; 静态成员函数对此尤其敏感. 可以考虑提取到新类中, 或者将函数置于独立库的命名空间内. 如果你必须定义非成员函数, 又只是在 ``.cc`` 文件中使用它, 可使用匿名 :ref:`namespaces` 或 ``static`` 链接关键字 (如 ``static int Foo() {...}``) 限定其作用域. +.. _local-variables: + 2.4. 局部变量 ~~~~~~~~~~~~~~~~~~~~~~ @@ -226,51 +212,67 @@ C++ 允许在函数的任何位置声明变量. 我们提倡在尽可能小的 int i; i = f(); // 坏——初始化和声明分离 + + .. code-block:: c++ + int j = g(); // 好——初始化时声明 + .. code-block:: c++ + vector v; v.push_back(1); // 用花括号初始化更好 v.push_back(2); + .. code-block:: c++ + vector v = {1, 2}; // 好——v 一开始就初始化 -注意, GCC 可正确实现了 ``for (int i = 0; i < 10; ++i)`` (``i`` 的作用域仅限 ``for`` 循环内), 所以其他 ``for`` 循环中可以重新使用 ``i``. 在 ``if`` 和 ``while`` 等语句中的作用域声明也是正确的, 如: +属于 ``if``, ``while`` 和 ``for`` 语句的变量应当在这些语句中正常地声明，这样子这些变量的作用域就被限制在这些语句中了，举例而言: .. code-block:: c++ while (const char* p = strchr(str, '/')) str = p + 1; - .. warning:: 如果变量是一个对象, 每次进入作用域都要调用其构造函数, 每次退出作用域都要调用其析构函数. +.. warning:: 有一个例外, 如果变量是一个对象, 每次进入作用域都要调用其构造函数, 每次退出作用域都要调用其析构函数. 这会导致效率降低. - .. code-block:: c++ +.. code-block:: c++ - // 低效的实现 - for (int i = 0; i < 1000000; ++i) { - Foo f; // 构造函数和析构函数分别调用 1000000 次! - f.DoSomething(i); - } + // 低效的实现 + for (int i = 0; i < 1000000; ++i) { + Foo f; // 构造函数和析构函数分别调用 1000000 次! + f.DoSomething(i); + } 在循环作用域外面声明这类变量要高效的多: - .. code-block:: c++ +.. code-block:: c++ - Foo f; // 构造函数和析构函数只调用 1 次 - for (int i = 0; i < 1000000; ++i) { - f.DoSomething(i); - } + Foo f; // 构造函数和析构函数只调用 1 次 + for (int i = 0; i < 1000000; ++i) { + f.DoSomething(i); + } + +.. _static-and-global-variables: 2.5. 静态和全局变量 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tip:: - 禁止使用 ``class`` 类型的静态或全局变量：它们会导致难以发现的 bug 和不确定的构造和析构函数调用顺序。不过 ``constexpr`` 变量除外，毕竟它们又不涉及动态初始化或析构。 + 禁止定义静态储存周期非POD变量，禁止使用含有副作用的函数初始化POD全局变量，因为多编译单元中的静态变量执行时的构造和析构顺序是未明确的，这将导致代码的不可移植。 + +禁止使用类的 `静态储存周期 `_ 变量：由于构造和析构函数调用顺序的不确定性，它们会导致难以发现的 bug 。不过 ``constexpr`` 变量除外，毕竟它们又不涉及动态初始化或析构。 静态生存周期的对象，即包括了全局变量，静态变量，静态类成员变量和函数静态变量，都必须是原生数据类型 (POD : Plain Old Data): 即 int, char 和 float, 以及 POD 类型的指针、数组和结构体。 -静态变量的构造函数、析构函数和初始化的顺序在 C++ 中是不确定的，甚至随着构建变化而变化，导致难以发现的 bug. 所以除了禁用类类型的全局变量，我们也不允许用函数返回值来初始化 POD 变量，除非该函数不涉及（比如 getenv() 或 getpid()）不涉及任何全局变量。（函数作用域里的静态变量除外，毕竟它的初始化顺序是有明确定义的，而且只会在指令执行到它的声明那里才会发生。） +静态变量的构造函数、析构函数和初始化的顺序在 C++ 中是只有部分明确的，甚至随着构建变化而变化，导致难以发现的 bug. 所以除了禁用类类型的全局变量，我们也不允许用函数返回值来初始化 POD 变量，除非该函数（比如 ``getenv()`` 或 ``getpid()`` ）不涉及任何全局变量。函数作用域里的静态变量除外，毕竟它的初始化顺序是有明确定义的，而且只会在指令执行到它的声明那里才会发生。 + +.. note:: Xris 译注: + + 同一个编译单元内是明确的，静态初始化优先于动态初始化，初始化顺序按照声明顺序进行，销毁则逆序。不同的编译单元之间初始化和销毁顺序属于未明确行为 (unspecified behaviour)。 + 同理，全局和静态变量在程序中断时会被析构，无论所谓中断是从 ``main()`` 返回还是对 ``exit()`` 的调用。析构顺序正好与构造函数调用的顺序相反。但既然构造顺序未定义，那么析构顺序当然也就不定了。比如，在程序结束时某静态变量已经被析构了，但代码还在跑——比如其它线程——并试图访问它且失败；再比如，一个静态 string 变量也许会在一个引用了前者的其它变量析构之前被析构掉。