mirror of
https://github.com/zh-google-styleguide/zh-google-styleguide.git
synced 2025-02-19 20:50:10 +08:00
6175eeafa8
Remove paragraphs that does not exists in original text and add new paragraphs and contents . Fix some translation issues.
305 lines
14 KiB
ReStructuredText
305 lines
14 KiB
ReStructuredText
2. 作用域
|
||
----------------
|
||
|
||
.. _namespaces:
|
||
|
||
2.1. 命名空间
|
||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
.. tip::
|
||
|
||
鼓励在 ``.cc`` 文件内使用匿名命名空间或 ``static`` 声明. 使用具名的命名空间时, 其名称可基于项目名或相对路径. 禁止使用 using 指示（using-directive）。禁止使用内联命名空间（inline namespace）。
|
||
|
||
**定义:**
|
||
|
||
命名空间将全局作用域细分为独立的, 具名的作用域, 可有效防止全局作用域的命名冲突.
|
||
|
||
**优点:**
|
||
|
||
虽然类已经提供了（可嵌套的）命名轴线 (YuleFox 注: 将命名分割在不同类的作用域内), 命名空间在这基础上又封装了一层.
|
||
|
||
举例来说, 两个不同项目的全局作用域都有一个类 ``Foo``, 这样在编译或运行时造成冲突. 如果每个项目将代码置于不同命名空间中, ``project1::Foo`` 和 ``project2::Foo`` 作为不同符号自然不会冲突.
|
||
|
||
内联命名空间会自动把内部的标识符放到外层作用域，比如：
|
||
|
||
.. code-block:: c++
|
||
|
||
namespace X {
|
||
inline namespace Y {
|
||
void foo();
|
||
} // namespace Y
|
||
} // namespace X
|
||
|
||
``X::Y::foo()`` 与 ``X::foo()`` 彼此可代替。内联命名空间主要用来保持跨版本的 ABI 兼容性。
|
||
|
||
**缺点:**
|
||
|
||
命名空间具有迷惑性, 因为它们使得区分两个相同命名所指代的定义更加困难。
|
||
|
||
内联命名空间很容易令人迷惑，毕竟其内部的成员不再受其声明所在命名空间的限制。内联命名空间只在大型版本控制里有用。
|
||
|
||
有时候不得不多次引用某个定义在许多嵌套命名空间里的实体，使用完整的命名空间会导致代码的冗长。
|
||
|
||
在头文件中使用匿名空间导致违背 C++ 的唯一定义原则 (One Definition Rule (ODR)).
|
||
|
||
**结论:**
|
||
|
||
根据下文将要提到的策略合理使用命名空间.
|
||
|
||
- 遵守 `命名空间命名 <naming.html#namespace-names>`_ 中的规则。
|
||
|
||
- 像之前的几个例子中一样，在命名空间的最后注释出命名空间的名字。
|
||
|
||
- 用命名空间把文件包含, `gflags <https://gflags.github.io/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`` 文件包含更多, 更复杂的细节, 比如 gflags 或 using 声明。
|
||
|
||
.. code-block:: c++
|
||
|
||
#include "a.h"
|
||
|
||
DEFINE_FLAG(bool, someflag, false, "dummy flag");
|
||
|
||
namespace a {
|
||
|
||
...code for a... // 左对齐
|
||
|
||
} // namespace a
|
||
|
||
- 不要在命名空间 ``std`` 内声明任何东西, 包括标准库的类前置声明. 在 ``std`` 命名空间声明实体是未定义的行为, 会导致如不可移植. 声明标准库下的实体, 需要包含对应的头文件.
|
||
|
||
- 不应该使用 *using 指示* 引入整个命名空间的标识符号。
|
||
|
||
.. code-block:: c++
|
||
|
||
// 禁止 —— 污染命名空间
|
||
using namespace foo;
|
||
|
||
- 不要在头文件中使用 *命名空间别名* 除非显式标记内部命名空间使用。因为任何在头文件中引入的命名空间都会成为公开API的一部分。
|
||
|
||
.. code-block:: c++
|
||
|
||
// 在 .cc 中使用别名缩短常用的命名空间
|
||
namespace baz = ::foo::bar::baz;
|
||
|
||
.. code-block:: c++
|
||
|
||
// 在 .h 中使用别名缩短常用的命名空间
|
||
namespace librarian {
|
||
namespace impl { // 仅限内部使用
|
||
namespace sidetable = ::pipeline_diagnostics::sidetable;
|
||
} // namespace impl
|
||
|
||
inline void my_inline_function() {
|
||
// 限制在一个函数中的命名空间别名
|
||
namespace baz = ::foo::bar::baz;
|
||
...
|
||
}
|
||
} // namespace librarian
|
||
|
||
- 禁止用内联命名空间
|
||
|
||
.. _unnamed-namespace-and-static-variables:
|
||
|
||
2.2. 匿名命名空间和静态变量
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
.. tip::
|
||
|
||
在 ``.cc`` 文件中定义一个不需要被外部引用的变量时，可以将它们放在匿名命名空间或声明为 ``static`` 。但是不要在 ``.h`` 文件中这么做。
|
||
|
||
**定义:**
|
||
|
||
所有置于匿名命名空间的声明都具有内部链接性，函数和变量可以经由声明为 ``static`` 拥有内部链接性，这意味着你在这个文件中声明的这些标识符都不能在另一个文件中被访问。即使两个文件声明了完全一样名字的标识符，它们所指向的实体实际上是完全不同的。
|
||
|
||
**结论:**
|
||
|
||
推荐、鼓励在 ``.cc`` 中对于不需要在其他地方引用的标识符使用内部链接性声明，但是不要在 ``.h`` 中使用。
|
||
|
||
匿名命名空间的声明和具名的格式相同，在最后注释上 ``namespace`` :
|
||
|
||
.. code-block:: c++
|
||
|
||
namespace {
|
||
...
|
||
} // namespace
|
||
|
||
.. _nonmember-static-member-and-global-functions:
|
||
|
||
2.3. 非成员函数、静态成员函数和全局函数
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
.. tip::
|
||
|
||
使用静态成员函数或命名空间内的非成员函数, 尽量不要用裸的全局函数. 将一系列函数直接置于命名空间中，不要用类的静态方法模拟出命名空间的效果，类的静态方法应当和类的实例或静态数据紧密相关.
|
||
|
||
**优点:**
|
||
|
||
某些情况下, 非成员函数和静态成员函数是非常有用的, 将非成员函数放在命名空间内可避免污染全局作用域.
|
||
|
||
**缺点:**
|
||
|
||
将非成员函数和静态成员函数作为新类的成员或许更有意义, 当它们需要访问外部资源或具有重要的依赖关系时更是如此.
|
||
|
||
**结论:**
|
||
|
||
有时, 把函数的定义同类的实例脱钩是有益的, 甚至是必要的. 这样的函数可以被定义成静态成员, 或是非成员函数. 非成员函数不应依赖于外部变量, 应尽量置于某个命名空间内. 相比单纯为了封装若干不共享任何静态数据的静态成员函数而创建类, 不如使用 :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. 局部变量
|
||
~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
.. tip::
|
||
|
||
将函数变量尽可能置于最小作用域内, 并在变量声明时进行初始化.
|
||
|
||
C++ 允许在函数的任何位置声明变量. 我们提倡在尽可能小的作用域中声明变量, 离第一次使用越近越好. 这使得代码浏览者更容易定位变量声明的位置, 了解变量的类型和初始值. 特别是，应使用初始化的方式替代声明再赋值, 比如:
|
||
|
||
.. code-block:: c++
|
||
|
||
int i;
|
||
i = f(); // 坏——初始化和声明分离
|
||
|
||
.. code-block:: c++
|
||
|
||
int j = g(); // 好——初始化时声明
|
||
|
||
.. code-block:: c++
|
||
|
||
vector<int> v;
|
||
v.push_back(1); // 用花括号初始化更好
|
||
v.push_back(2);
|
||
|
||
.. code-block:: c++
|
||
|
||
vector<int> v = {1, 2}; // 好——v 一开始就初始化
|
||
|
||
|
||
属于 ``if``, ``while`` 和 ``for`` 语句的变量应当在这些语句中正常地声明，这样子这些变量的作用域就被限制在这些语句中了，举例而言:
|
||
|
||
.. 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);
|
||
}
|
||
|
||
.. _static-and-global-variables:
|
||
|
||
2.5. 静态和全局变量
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
.. tip::
|
||
|
||
禁止定义静态储存周期非POD变量，禁止使用含有副作用的函数初始化POD全局变量，因为多编译单元中的静态变量执行时的构造和析构顺序是未明确的，这将导致代码的不可移植。
|
||
|
||
禁止使用类的 `静态储存周期 <http://zh.cppreference.com/w/cpp/language/storage_duration#.E5.AD.98.E5.82.A8.E6.9C.9F>`_ 变量：由于构造和析构函数调用顺序的不确定性，它们会导致难以发现的 bug 。不过 ``constexpr`` 变量除外，毕竟它们又不涉及动态初始化或析构。
|
||
|
||
静态生存周期的对象，即包括了全局变量，静态变量，静态类成员变量和函数静态变量，都必须是原生数据类型 (POD : Plain Old Data): 即 int, char 和 float, 以及 POD 类型的指针、数组和结构体。
|
||
|
||
静态变量的构造函数、析构函数和初始化的顺序在 C++ 中是只有部分明确的，甚至随着构建变化而变化，导致难以发现的 bug. 所以除了禁用类类型的全局变量，我们也不允许用函数返回值来初始化 POD 变量，除非该函数（比如 ``getenv()`` 或 ``getpid()`` ）不涉及任何全局变量。函数作用域里的静态变量除外，毕竟它的初始化顺序是有明确定义的，而且只会在指令执行到它的声明那里才会发生。
|
||
|
||
.. note:: Xris 译注:
|
||
|
||
同一个编译单元内是明确的，静态初始化优先于动态初始化，初始化顺序按照声明顺序进行，销毁则逆序。不同的编译单元之间初始化和销毁顺序属于未明确行为 (unspecified behaviour)。
|
||
|
||
|
||
同理，全局和静态变量在程序中断时会被析构，无论所谓中断是从 ``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:: Yang.Y 译注:
|
||
|
||
上文提及的静态变量泛指静态生存周期的对象, 包括: 全局变量, 静态变量, 静态类成员变量, 以及函数静态变量.
|
||
|
||
译者 (YuleFox) 笔记
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
#. ``cc`` 中的匿名命名空间可避免命名冲突, 限定作用域, 避免直接使用 ``using`` 关键字污染命名空间;
|
||
#. 嵌套类符合局部使用原则, 只是不能在其他头文件中前置声明, 尽量不要 ``public``;
|
||
#. 尽量不用全局函数和全局变量, 考虑作用域和命名空间限制, 尽量单独形成编译单元;
|
||
#. 多线程中的全局变量 (含静态成员变量) 不要使用 ``class`` 类型 (含 STL 容器), 避免不明确行为导致的 bug.
|
||
#. 作用域的使用, 除了考虑名称污染, 可读性之外, 主要是为降低耦合, 提高编译/执行效率.
|
||
|
||
译者（acgtyrant）笔记
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
#. 注意「using 指示（using-directive）」和「using 声明（using-declaration）」的区别。
|
||
#. 匿名命名空间说白了就是文件作用域，就像 C static 声明的作用域一样，后者已经被 C++ 标准提倡弃用。
|
||
#. 局部变量在声明的同时进行显式值初始化，比起隐式初始化再赋值的两步过程要高效，同时也贯彻了计算机体系结构重要的概念「局部性（locality）」。
|
||
#. 注意别在循环犯大量构造和析构的低级错误。
|