zh-google-styleguide/google-cpp-styleguide/scoping.rst

2. 作用域
--------

.. _namespaces:

2.1. 名字空间
~~~~~~~~~~~~

.. tip::

    鼓励在 ``.cc`` 文件内使用匿名名字空间. 使用具名的名字空间时, 其名称可基于项目名或相对路径. 禁止使用 using 指示（using-directive）。禁止使用内联命名空间（inline namespace）。

定义:

    名字空间将全局作用域细分为独立的, 具名的作用域, 可有效防止全局作用域的命名冲突.

优点:

    虽然类已经提供了（可嵌套的）命名轴线 (YuleFox 注: 将命名分割在不同类的作用域内), 名字空间在这基础上又封装了一层.

    举例来说, 两个不同项目的全局作用域都有一个类 ``Foo``, 这样在编译或运行时造成冲突. 如果每个项目将代码置于不同名字空间中, ``project1::Foo`` 和 ``project2::Foo`` 作为不同符号自然不会冲突.

    内联命名空间会自动把内部的标识符放到外层作用域，比如：

    .. code-block:: c++

        namespace X {
        inline namespace Y {
        void foo();
        }
        }

    ``X::Y::foo()`` 与 ``X::foo()`` 彼此可代替。内联命名空间主要用来保持跨版本的 ABI 兼容性。

缺点:

    名字空间具有迷惑性, 因为它们和类一样提供了额外的 (可嵌套的) 命名轴线.

    命名空间很容易令人迷惑，毕竟它们不再受其声明所在命名空间的限制。内联命名空间只在大型版本控制里有用。

    在头文件中使用匿名空间导致违背 C++ 的唯一定义原则 (One Definition Rule (ODR)).

结论:

    根据下文将要提到的策略合理使用命名空间.

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 <http://code.google.com/p/google-gflags/>`_ 的声明/定义, 以及类的前置声明以外的整个源文件封装起来, 以区别于其它名字空间:

        .. code-block:: c++

            // .h 文件
            namespace mynamespace {

            // 所有声明都置于命名空间中
            // 注意不要使用缩进
            class MyClass {
                public:
                …
                void Foo();
            };

            } // namespace mynamespace

        .. code-block:: c++

            // .cc 文件
            namespace mynamespace {

            // 函数定义都置于命名空间中
            void MyClass::Foo() {
                …
            }

            } // namespace mynamespace

        通常的 ``.cc`` 文件包含更多, 更复杂的细节, 比如引用其他名字空间的类等.

        .. code-block:: c++

            #include “a.h”

            DEFINE_bool(someflag, false, “dummy flag”);

            class C;                    // 全局名字空间中类 C 的前置声明
            namespace a { class A; }    // a::A 的前置声明

            namespace b {

            …code for b…                // b 中的代码

            } // namespace b


    - 不要在名字空间 ``std`` 内声明任何东西, 包括标准库的类前置声明. 在 ``std`` 名字空间声明实体会导致不确定的问题, 比如不可移植. 声明标准库下的实体, 需要包含对应的头文件.

    - 最好不要使用 using 指示，以保证名字空间下的所有名称都可以正常使用.

        .. code-block:: c++

            // 禁止 —— 污染名字空间
            using namespace foo;

    - 在 ``.cc`` 文件, ``.h`` 文件的函数, 方法或类中, 可以使用 using 声明。

        .. code-block:: c++

            // 允许: .cc 文件中
            // .h 文件的话, 必须在函数, 方法或类的内部使用
            using ::foo::bar;

    - 在 ``.cc`` 文件, ``.h`` 文件的函数, 方法或类中, 允许使用名字空间别名.

        .. code-block:: c++

            // 允许: .cc 文件中
            // .h 文件的话, 必须在函数, 方法或类的内部使用

            namespace fbz = ::foo::bar::baz;

            // 在 .h 文件里
            namespace librarian {
            //以下别名在所有包含了该头文件的文件中生效。
            namespace pd_s = ::pipeline_diagnostics::sidetable;

            inline void my_inline_function() {
              // namespace alias local to a function (or method).
              namespace fbz = ::foo::bar::baz;
              ...
            }
            }  // namespace librarian

        注意在 .h 文件的别名对包含了该头文件的所有人可见，所以在公共头文件（在项目外可用）以及它们递归包含的其它头文件里，不要用别名。毕竟原则上公共 API 要尽可能地精简。

    - 禁止用内联命名空间

2.2. 嵌套类
~~~~~~~~~

.. tip::

    当公有嵌套类作为接口的一部分时, 虽然可以直接将他们保持在全局作用域中, 但将嵌套类的声明置于:ref:`namespaces`内是更好的选择.

定义: 在一个类内部定义另一个类; 嵌套类也被称为 *成员类 (member class)*.

    .. code-block:: c++

        class Foo {

        private:
            // Bar是嵌套在Foo中的成员类
            class Bar {
                …
            };

        };

优点:

    当嵌套 (或成员) 类只被外围类使用时非常有用; 把它作为外围类作用域内的成员, 而不是去污染外部作用域的同名类. 嵌套类可以在外围类中做前置声明, 然后在 ``.cc`` 文件中定义, 这样避免在外围类的声明中定义嵌套类, 因为嵌套类的定义通常只与实现相关.

缺点:

    嵌套类只能在外围类的内部做前置声明. 因此, 任何使用了 ``Foo::Bar*`` 指针的头文件不得不包含类 ``Foo`` 的整个声明.

结论:

    不要将嵌套类定义成公有, 除非它们是接口的一部分, 比如, 嵌套类含有某些方法的一组选项.

2.3. 非成员函数、静态成员函数和全局函数
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. tip::

    使用静态成员函数或名字空间内的非成员函数, 尽量不要用裸的全局函数.

优点:

    某些情况下, 非成员函数和静态成员函数是非常有用的, 将非成员函数放在名字空间内可避免污染全局作用域.

缺点:

    将非成员函数和静态成员函数作为新类的成员或许更有意义, 当它们需要访问外部资源或具有重要的依赖关系时更是如此.

结论:

    有时, 把函数的定义同类的实例脱钩是有益的, 甚至是必要的. 这样的函数可以被定义成静态成员, 或是非成员函数. 非成员函数不应依赖于外部变量, 应尽量置于某个名字空间内. 相比单纯为了封装若干不共享任何静态数据的静态成员函数而创建类, 不如使用:ref:`namespaces`。

    定义在同一编译单元的函数, 被其他编译单元直接调用可能会引入不必要的耦合和链接时依赖; 静态成员函数对此尤其敏感. 可以考虑提取到新类中, 或者将函数置于独立库的名字空间内.

    如果你必须定义非成员函数, 又只是在 ``.cc`` 文件中使用它, 可使用匿名:ref:`namespaces`或 ``static`` 链接关键字 (如 ``static int Foo() {...}``) 限定其作用域.

2.4. 局部变量
~~~~~~~~~~~

.. tip::

    将函数变量尽可能置于最小作用域内, 并在变量声明时进行初始化.

C++ 允许在函数的任何位置声明变量. 我们提倡在尽可能小的作用域中声明变量, 离第一次使用越近越好. 这使得代码浏览者更容易定位变量声明的位置, 了解变量的类型和初始值. 特别是，应使用初始化的方式替代声明再赋值, 比如:

    .. code-block:: c++

        int i;
        i = f(); // 坏——初始化和声明分离
        int j = g(); // 好——初始化时声明

        vector<int> v;
        v.push_back(1); // 用花括号初始化更好
        v.push_back(2);

        vector<int> v = {1, 2}; // 好——v 一开始就初始化


注意, GCC 可正确实现了 ``for (int i = 0; i < 10; ++i)`` (``i`` 的作用域仅限 ``for`` 循环内), 所以其他 ``for`` 循环中可以重新使用 ``i``. 在 ``if`` 和 ``while`` 等语句中的作用域声明也是正确的, 如:

    .. code-block:: c++

        while (const char* p = strchr(str, ‘/’)) str = p + 1;


    .. warning:: 如果变量是一个对象, 每次进入作用域都要调用其构造函数, 每次退出作用域都要调用其析构函数.

    .. code-block:: c++

        // 低效的实现
        for (int i = 0; i < 1000000; ++i) {
            Foo f;                  // 构造函数和析构函数分别调用 1000000 次!
            f.DoSomething(i);
        }

在循环作用域外面声明这类变量要高效的多:

    .. code-block:: c++

        Foo f;                      // 构造函数和析构函数只调用 1 次
        for (int i = 0; i < 1000000; ++i) {
            f.DoSomething(i);
        }

2.5. 静态和全局变量
~~~~~~~~~~~~~~~~

.. tip::

    禁止使用 ``class`` 类型的静态或全局变量：它们会导致难以发现的 bug 和不确定的构造和析构函数调用顺序。不过 ``constexpr`` 变量除外，毕竟它们又不涉及动态初始化或析构。

静态生存周期的对象，即包括了全局变量，静态变量，静态类成员变量和函数静态变量，都必须是原生数据类型 (POD : Plain Old Data): 即 int, char 和 float, 以及 POD 类型的指针、数组和结构体。

静态变量的构造函数、析构函数和初始化的顺序在 C++ 中是不确定的，甚至随着构建变化而变化，导致难以发现的 bug. 所以除了禁用类类型的全局变量，我们也不允许用函数返回值来初始化 POD 变量，除非该函数不涉及（比如 getenv() 或 getpid()）不涉及任何全局变量。（函数作用域里的静态变量除外，毕竟它的初始化顺序是有明确定义的，而且只会在指令执行到它的声明那里才会发生。）

同理，全局和静态变量在程序中断时会被析构，无论所谓中断是从 ``main()`` 返回还是对 ``exit()`` 的调用。析构顺序正好与构造函数调用的顺序相反。但既然构造顺序未定义，那么析构顺序当然也就不定了。比如，在程序结束时某静态变量已经被析构了，但代码还在跑——比如其它线程——并试图访问它且失败；再比如，一个静态 string 变量也许会在一个引用了前者的其它变量析构之前被析构掉。

改善以上析构问题的办法之一是用 ``quick_exit()`` 来代替 ``exit()`` 并中断程序。它们的不同之处是前者不会执行任何析构，也不会执行 ``atexit()`` 所绑定的任何 handlers. 如果您想在执行 ``quick_exit()`` 来中断时执行某 handler（比如刷新 log），您可以把它绑定到 ``_at_quick_exit()``. 如果您想在 ``exit()`` 和 ``quick_exit()`` 都用上该 handler, 都绑定上去。

综上所述，我们只允许 POD 类型的静态变量，即完全禁用 ``vector`` (使用 C 数组替代) 和 ``string`` (使用 ``const char []``)。

如果您确实需要一个 ``class` 类型的静态或全局变量，可以考虑在 ``main()`` 函数或 ``pthread_once()`` 内初始化一个指针且永不回收。注意只能用 raw 指针，别用智能指针，毕竟后者的析构函数涉及到上文指出的不定顺序问题。

.. note:: yospaly 译注:

    上文提及的静态变量泛指静态生存周期的对象, 包括: 全局变量, 静态变量, 静态类成员变量, 以及函数静态变量.

译者 (YuleFox) 笔记
~~~~~~~~~~~~~~~~~~~~~~~~

#. ``cc`` 中的匿名名字空间可避免命名冲突, 限定作用域, 避免直接使用 ``using`` 关键字污染命名空间;
#. 嵌套类符合局部使用原则, 只是不能在其他头文件中前置声明, 尽量不要 ``public``;
#. 尽量不用全局函数和全局变量, 考虑作用域和命名空间限制, 尽量单独形成编译单元;
#. 多线程中的全局变量 (含静态成员变量) 不要使用 ``class`` 类型 (含 STL 容器), 避免不明确行为导致的 bug.
#. 作用域的使用, 除了考虑名称污染, 可读性之外, 主要是为降低耦合, 提高编译/执行效率.

译者（acgtyrant）笔记
~~~~~~~~~~~~~~~~~~~~~~~~

#. 注意「using 指示（using-directive）」和「using 声明（using-declaration）」的区别。
#. 匿名名字空间说白了就是文件作用域，就像 C static 声明的作用域一样，后者已经被 C++ 标准提倡弃用。
#. 局部变量在声明的同时进行显式值初始化，比起隐式初始化再赋值的两步过程要高效，同时也贯彻了计算机体系结构重要的概念「局部性（locality）」。
#. 注意别在循环犯大量构造和析构的低级错误。