mirror of
https://github.com/zh-google-styleguide/zh-google-styleguide.git
synced 2025-02-19 20:50:10 +08:00
重排
继续补充遗漏的断行。 统一译者笔记的列表符号为 # 在 tip 后全断行。
This commit is contained in:
acgtyrant
parent
092589c3ac
commit
34a31e7935
@ -9,6 +9,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
使用 ``//`` 或 ``/* */``, 统一就好.
|
||||
|
||||
``//`` 或 ``/* */`` 都可以; 但 ``//`` *更* 常用. 要在如何注释及注释风格上确保统一.
|
||||
@ -17,6 +18,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
在每一个文件开头加入版权公告, 然后是文件内容描述.
|
||||
|
||||
法律公告和作者信息:
|
||||
@ -45,6 +47,7 @@
|
||||
~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
每个类的定义都要附带一份注释, 描述类的功能和用法.
|
||||
|
||||
.. code-block:: c++
|
||||
@ -67,6 +70,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
函数声明处注释描述函数功能; 定义处描述函数实现.
|
||||
|
||||
函数声明:
|
||||
@ -121,6 +125,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
通常变量名本身足以很好说明变量用途. 某些情况下, 也需要额外的注释说明.
|
||||
|
||||
类数据成员:
|
||||
@ -149,6 +154,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
对于代码中巧妙的, 晦涩的, 有趣的, 重要的地方加以注释.
|
||||
|
||||
代码前注释:
|
||||
@ -212,7 +218,6 @@ NULL, true/false, 1, 2, 3...:
|
||||
false, // Not the first time we're calling this.
|
||||
NULL); // No callback.
|
||||
|
||||
|
||||
或使用常量或描述性变量:
|
||||
|
||||
.. code-block:: c++
|
||||
@ -230,6 +235,7 @@ NULL, true/false, 1, 2, 3...:
|
||||
注意 *永远不要* 用自然语言翻译代码作为注释. 要假设读代码的人 C++ 水平比你高, 即便他/她可能不知道你的用意:
|
||||
|
||||
.. warning::
|
||||
|
||||
.. code-block:: c++
|
||||
|
||||
// 现在, 检查 b 数组并确保 i 是否存在,
|
||||
@ -240,6 +246,7 @@ NULL, true/false, 1, 2, 3...:
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
注意标点, 拼写和语法; 写的好的注释比差的要易读的多.
|
||||
|
||||
注释的通常写法是包含正确大小写和结尾句号的完整语句. 短一点的注释 (如代码行尾注释) 可以随意点, 依然要注意风格的一致性. 完整的语句可读性更好, 也可以说明该注释是完整的, 而不是一些不成熟的想法.
|
||||
@ -250,6 +257,7 @@ NULL, true/false, 1, 2, 3...:
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 ``TODO`` 注释.
|
||||
|
||||
``TODO`` 注释要使用全大写的字符串 ``TODO``, 在随后的圆括号里写上你的大名, 邮件地址, 或其它身份标识. 冒号是可选的. 主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 ``TODO`` 格式进行查找. 添加 ``TODO`` 注释并不意味着你要自己来修正.
|
||||
@ -265,6 +273,7 @@ NULL, true/false, 1, 2, 3...:
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
通过弃用注释（``DEPRECATED`` comments）以标记某接口点（interface points）已弃用。
|
||||
|
||||
您可以写上包含全大写的 ``DEPRECATED`` 的注释，以标记某接口为弃用状态。注释可以放在接口声明前，或者同一行。
|
||||
|
||||
@ -7,6 +7,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
对于现有不符合既定编程风格的代码可以网开一面.
|
||||
|
||||
当你修改使用其他风格的代码时, 为了与代码原有风格保持一致可以不使用本指南约定. 如果不放心可以与代码原作者或现在的负责人员商讨, 记住, *一致性* 包括原有的一致性.
|
||||
@ -17,6 +18,7 @@
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
Windows 程序员有自己的编程习惯, 主要源于 Windows 头文件和其它 Microsoft 代码. 我们希望任何人都可以顺利读懂你的代码, 所以针对所有平台的 C++ 编程只给出一个单独的指南.
|
||||
|
||||
如果你习惯使用 Windows 编码风格, 这儿有必要重申一下某些你可能会忘记的指南:
|
||||
|
||||
@ -11,6 +11,7 @@
|
||||
~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
每一行代码字符数不超过 80.
|
||||
|
||||
我们也认识到这条规则是有争议的, 但很多已有代码都已经遵照这一规则, 我们感觉一致性更重要.
|
||||
@ -37,6 +38,7 @@
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
尽量不使用非 ASCII 字符, 使用时必须使用 UTF-8 编码.
|
||||
|
||||
即使是英文, 也不应将用户界面的文本硬编码到源代码中, 因此非 ASCII 字符要少用. 特殊情况下可以适当包含此类字符. 如, 代码分析外部数据文件时, 可以适当硬编码数据文件中作为分隔符的非 ASCII 字符串; 更常见的是 (不需要本地化的) 单元测试代码可能包含非 ASCII 字符串. 此类情况下, 应使用 UTF-8 编码, 因为很多工具都可以理解和处理 UTF-8 编码.
|
||||
@ -53,6 +55,7 @@
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
只使用空格, 每次缩进 2 个空格.
|
||||
|
||||
我们使用空格缩进. 不要在代码中使用制符表. 你应该设置编辑器将制符表转为空格.
|
||||
@ -61,6 +64,7 @@
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
返回类型和函数名在同一行, 参数也尽量放在同一行，如果放不下就对形参分行。
|
||||
|
||||
函数看上去像这样:
|
||||
@ -140,6 +144,7 @@
|
||||
void Circle::Rotate(double /*radians*/) {}
|
||||
|
||||
.. warning::
|
||||
|
||||
.. code-block:: c++
|
||||
|
||||
// 差 - 如果将来有人要实现，很难猜出变量是干什么用的。
|
||||
@ -149,6 +154,7 @@
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
其它函数怎么格式化形参和函数体，Lambda 表达式就怎么格式化；捕获列表同理。
|
||||
|
||||
若用引用捕获，在变量名和 ``&`` 之间不留空格。
|
||||
@ -173,6 +179,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
要么一行写完函数调用，要么在圆括号里对参数分行，要么参数另起一行且缩进四格。如果没有其它顾虑的话，尽可能精简行数，比如把多个参数适当地放在同一行里。
|
||||
|
||||
函数调用遵循如下形式：
|
||||
@ -234,6 +241,7 @@
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
您平时怎么格式化函数调用，就怎么格式化:ref:`braced_initializer_list`。
|
||||
|
||||
如果列表初始化伴随着名字，比如类型或变量名，您可以当名字是函数、{} 是函数调用的括号来格式化它。反之，就当它有个长度为零的名字。
|
||||
@ -270,6 +278,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
倾向于不在圆括号内使用空格. 关键字 ``if`` 和 ``else`` 另起一行.
|
||||
|
||||
对基本条件语句有两种可以接受的格式. 一种在圆括号和条件之间有空格, 另一种没有.
|
||||
@ -369,6 +378,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
``switch`` 语句可以使用大括号分段，以表明 cases 之间不是连在一起的。在单语句循环里，括号可用可不用。空循环体应使用 ``{}`` 或 ``continue``.
|
||||
|
||||
``switch`` 语句中的 ``case`` 块可以使用大括号也可以不用, 取决于你的个人喜好. 如果用的话, 要按照下文所述的方法.
|
||||
@ -422,6 +432,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
句点或箭头前后不要有空格. 指针/地址操作符 (``*, &``) 之后不能有空格.
|
||||
|
||||
下面是指针和引用表达式的正确使用范例:
|
||||
@ -462,6 +473,7 @@
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
如果一个布尔表达式超过 :ref:`标准行宽 <line-length>`, 断行方式要统一一下.
|
||||
|
||||
下例中, 逻辑与 (``&&``) 操作符总位于行尾:
|
||||
@ -480,6 +492,7 @@
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
``return`` 表达式里时没必要都用圆括号。
|
||||
|
||||
在 ``return expr;`` 里就用圆括号，当且只当您会在 ``x = epr;`` 用上它们（acgtyrant 注：字面上的意思就是这样，我也不知怎么理解，只能直译了；我猜意为「当且只当您用该函数的返回值赋值给某变量」）。
|
||||
@ -504,6 +517,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
用 ``=``, ``()`` 和 ``{}`` 均可.
|
||||
|
||||
您可以用 ``=``, ``()`` 和 ``{}``, 以下都对：
|
||||
@ -535,6 +549,7 @@
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
预处理指令不要缩进, 从行首开始.
|
||||
|
||||
即使预处理指令位于缩进代码块中, 指令也应从行首开始.
|
||||
@ -565,6 +580,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
访问控制块的声明依次序是 ``public:``, ``protected:``, ``private:``, 每次缩进 1 个空格.
|
||||
|
||||
类声明 (对类注释不了解的话, 参考 :ref:`类注释 <class-comments>`) 的基本格式如下:
|
||||
@ -610,6 +626,7 @@
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
构造函数初始化列表放在同一行或按四格缩进并排几行.
|
||||
|
||||
下面两种初始化列表方式都可以接受:
|
||||
@ -636,6 +653,7 @@
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
名字空间内容不缩进.
|
||||
|
||||
:ref:`名字空间 <namespaces>` 不要增加额外的缩进层次, 例如:
|
||||
@ -674,7 +692,9 @@
|
||||
|
||||
8.18. 水平留白
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
水平留白的使用因地制宜. 永远不要在行尾添加没意义的留白.
|
||||
|
||||
常规:
|
||||
@ -754,6 +774,7 @@
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
垂直留白越少越好.
|
||||
|
||||
这不仅仅是规则而是原则问题了: 不在万不得已, 不要使用空行. 尤其是: 两个函数定义之间的空行不要超过 2 行, 函数体首尾不要留空行, 函数体中也不要随意添加空行.
|
||||
@ -768,25 +789,25 @@
|
||||
译者 (YuleFox) 笔记
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
*. 对于代码格式, 因人, 系统而异各有优缺点, 但同一个项目中遵循同一标准还是有必要的;
|
||||
1. 行宽原则上不超过 80 列, 把 22 寸的显示屏都占完, 怎么也说不过去;
|
||||
2. 尽量不使用非 ASCII 字符, 如果使用的话, 参考 UTF-8 格式 (尤其是 UNIX/Linux 下, Windows 下可以考虑宽字符), 尽量不将字符串常量耦合到代码中, 比如独立出资源文件, 这不仅仅是风格问题了;
|
||||
3. UNIX/Linux 下无条件使用空格, MSVC 的话使用 Tab 也无可厚非;
|
||||
4. 函数参数, 逻辑条件, 初始化列表: 要么所有参数和函数名放在同一行, 要么所有参数并排分行;
|
||||
5. 除函数定义的左大括号可以置于行首外, 包括函数/类/结构体/枚举声明, 各种语句的左大括号置于行尾, 所有右大括号独立成行;
|
||||
6. ``.``/``->`` 操作符前后不留空格, ``*``/``&`` 不要前后都留, 一个就可, 靠左靠右依各人喜好;
|
||||
7. 预处理指令/命名空间不使用额外缩进, 类/结构体/枚举/函数/语句使用缩进;
|
||||
8. 初始化用 ``=`` 还是 ``()`` 依个人喜好, 统一就好;
|
||||
9. ``return`` 不要加 ``()``;
|
||||
10. 水平/垂直留白不要滥用, 怎么易读怎么来.
|
||||
11. 关于 UNIX/Linux 风格为什么要把左大括号置于行尾 (``.cc`` 文件的函数实现处, 左大括号位于行首), 我的理解是代码看上去比较简约, 想想行首除了函数体被一对大括号封在一起之外, 只有右大括号的代码看上去确实也舒服; Windows 风格将左大括号置于行首的优点是匹配情况一目了然.
|
||||
#. 对于代码格式, 因人, 系统而异各有优缺点, 但同一个项目中遵循同一标准还是有必要的;
|
||||
#. 行宽原则上不超过 80 列, 把 22 寸的显示屏都占完, 怎么也说不过去;
|
||||
#. 尽量不使用非 ASCII 字符, 如果使用的话, 参考 UTF-8 格式 (尤其是 UNIX/Linux 下, Windows 下可以考虑宽字符), 尽量不将字符串常量耦合到代码中, 比如独立出资源文件, 这不仅仅是风格问题了;
|
||||
#. UNIX/Linux 下无条件使用空格, MSVC 的话使用 Tab 也无可厚非;
|
||||
#. 函数参数, 逻辑条件, 初始化列表: 要么所有参数和函数名放在同一行, 要么所有参数并排分行;
|
||||
#. 除函数定义的左大括号可以置于行首外, 包括函数/类/结构体/枚举声明, 各种语句的左大括号置于行尾, 所有右大括号独立成行;
|
||||
#. ``.``/``->`` 操作符前后不留空格, ``*``/``&`` 不要前后都留, 一个就可, 靠左靠右依各人喜好;
|
||||
#. 预处理指令/命名空间不使用额外缩进, 类/结构体/枚举/函数/语句使用缩进;
|
||||
#. 初始化用 ``=`` 还是 ``()`` 依个人喜好, 统一就好;
|
||||
#. ``return`` 不要加 ``()``;
|
||||
#. 水平/垂直留白不要滥用, 怎么易读怎么来.
|
||||
#. 关于 UNIX/Linux 风格为什么要把左大括号置于行尾 (``.cc`` 文件的函数实现处, 左大括号位于行首), 我的理解是代码看上去比较简约, 想想行首除了函数体被一对大括号封在一起之外, 只有右大括号的代码看上去确实也舒服; Windows 风格将左大括号置于行首的优点是匹配情况一目了然.
|
||||
|
||||
译者（acgtyrant）笔记
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* 80 行限制事实上有助于避免代码可读性失控，比如超多重嵌套块，超多重函数调用等等。
|
||||
* Linux 上设置好了 Locale 就几乎一劳永逸设置好所有开发环境的编码，不像奇葩的 Windows.
|
||||
* Google 强调有一对 if-else 时，不论有没有嵌套，都要有大括号。Apple 正好`有栽过跟头 <http://coolshell.cn/articles/11112.html>`_.
|
||||
* 其实我主张指针／地址操作符与变量名紧邻，``int* a, b`` vs ``int *a, b``, 新手会误以为前者的 ``b`` 是 ``int *`` 变量，但后者就不一样了，高下立判。
|
||||
* 在这风格指南里我才刚知道 C++ 原来还有所谓的 `Alternative operator representations <http://en.cppreference.com/w/cpp/language/operator_alternative>`_, 大概没人用吧。
|
||||
* 事实上，如果您熟悉英语本身的书写规则，就会发现该风格指南在格式上的规定与英语语法相当一脉相承。比如普通标点符号和单词后面还有文本的话，总会留一个空格；特殊符号与单词之间就不用留了，比如 ``if (true)`` 中的圆括号与 ``true``.
|
||||
# 80 行限制事实上有助于避免代码可读性失控，比如超多重嵌套块，超多重函数调用等等。
|
||||
# Linux 上设置好了 Locale 就几乎一劳永逸设置好所有开发环境的编码，不像奇葩的 Windows.
|
||||
# Google 强调有一对 if-else 时，不论有没有嵌套，都要有大括号。Apple 正好`有栽过跟头 <http://coolshell.cn/articles/11112.html>`_.
|
||||
# 其实我主张指针／地址操作符与变量名紧邻，``int* a, b`` vs ``int *a, b``, 新手会误以为前者的 ``b`` 是 ``int *`` 变量，但后者就不一样了，高下立判。
|
||||
# 在这风格指南里我才刚知道 C++ 原来还有所谓的 `Alternative operator representations <http://en.cppreference.com/w/cpp/language/operator_alternative>`_, 大概没人用吧。
|
||||
# 事实上，如果您熟悉英语本身的书写规则，就会发现该风格指南在格式上的规定与英语语法相当一脉相承。比如普通标点符号和单词后面还有文本的话，总会留一个空格；特殊符号与单词之间就不用留了，比如 ``if (true)`` 中的圆括号与 ``true``.
|
||||
|
||||
@ -13,6 +13,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
头文件应该能够自给自足（self-contained），以 ``in.h`` 结尾。至于用来插入文本的文件，说到底它们并不是头文件，所以应以 ``.inc`` 结尾。
|
||||
|
||||
所有头文件要能够自给自足。换言之，用户和重构工具不需要为特别场合而包含额外的头文件。详言之，一个头文件要有 :ref:`define-guard`，统统包含它所需要的其它头文件，也不要求定义任何特别 symbols.
|
||||
@ -29,6 +30,7 @@ As an exception, a function template that is explicitly instantiated for all rel
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
所有头文件都应该使用 ``#define`` 防止头文件被多重包含, 命名格式当是: ``<PROJECT>_<PATH>_<FILE>_H_``
|
||||
|
||||
为保证唯一性, 头文件的命名应该依据所在项目源代码树的全路径. 例如, 项目 ``foo`` 中的头文件 ``foo/src/bar/baz.h`` 可按如下方式保护:
|
||||
@ -46,6 +48,7 @@ As an exception, a function template that is explicitly instantiated for all rel
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
您可以靠前置声明来避免多余的 ``#includes``.
|
||||
|
||||
定义：
|
||||
@ -82,6 +85,7 @@ As an exception, a function template that is explicitly instantiated for all rel
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
只有当函数只有 10 行甚至更少时才将其定义为内联函数.
|
||||
|
||||
定义:
|
||||
@ -108,6 +112,7 @@ As an exception, a function template that is explicitly instantiated for all rel
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
定义函数时, 参数顺序依次为: 输入参数, 然后是输出参数.
|
||||
|
||||
C/C++ 函数参数分为输入参数, 输出参数, 和输入/输出参数三种. 输入参数一般传值或传 ``const`` 引用, 输出参数或输入/输出参数则是非-``const`` 指针. 对参数排序时, 将只输入的参数放在所有输出参数之前. 尤其是不要仅仅因为是新加的参数, 就把它放在最后; 即使是新加的只输入参数也要放在输出参数之前.
|
||||
|
||||
@ -7,6 +7,7 @@ Google 用了很多自己实现的技巧 / 工具使 C++ 代码更加健壮, 我
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
动态分配出的对象最好有单一且固定的所有主（onwer）, 且通过智能指针传递所有权（ownership）.
|
||||
|
||||
定义：
|
||||
@ -40,6 +41,7 @@ Google 用了很多自己实现的技巧 / 工具使 C++ 代码更加健壮, 我
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
使用 ``cpplint.py`` 检查风格错误.
|
||||
|
||||
``cpplint.py`` 是一个用来分析源文件, 能检查出多种风格错误的工具. 它不并完美, 甚至还会漏报和误报, 但它仍然是一个非常有用的工具. 在行尾加 ``// NOLINT``, 或在上一行加 ``// NOLINTNEXTLINE``, 可以忽略报错。
|
||||
|
||||
@ -9,6 +9,7 @@
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
函数命名，变量命名，文件命名要有描述性；少用缩写。
|
||||
|
||||
尽可能给有描述性的命名，别心疼空间，毕竟让代码易于新读者理解很重要。不要用只有项目开发者能理解的缩写，也不要通过砍掉几个字母来缩写单词。
|
||||
@ -34,6 +35,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
文件名要全部小写, 可以包含下划线 (``_``) 或连字符 (``-``). 按项目约定来. 如果并没有项目约定，"_" 更好。
|
||||
|
||||
可接受的文件命名::
|
||||
@ -55,9 +57,11 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
类型名称的每个单词首字母均大写, 不包含下划线: ``MyExcitingClass``, ``MyExcitingEnum``.
|
||||
|
||||
所有类型命名 —— 类, 结构体, 类型定义 (``typedef``), 枚举 —— 均使用相同约定. 例如:
|
||||
|
||||
.. code-block:: c++
|
||||
|
||||
// classes and structs
|
||||
@ -75,6 +79,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
变量名一律小写, 单词之间用下划线连接. 类的成员变量以下划线结尾, 但结构体的就不用，如:: ``a_local_variable``, ``a_struct_data_member``, ``a_class_data_member_``.
|
||||
|
||||
普通变量命名:
|
||||
@ -126,6 +131,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
在全局或类里的常量名称前加 ``k``: kDaysInAWeek. 且除去开头的 ``k`` 之外每个单词开头字母均大写。
|
||||
|
||||
所有编译时常量, 无论是局部的, 全局的还是类中的, 和其他变量稍微区别一下. ``k`` 后接大写字母开头的单词:
|
||||
@ -136,13 +142,13 @@
|
||||
|
||||
这规则适用于编译时的局部作用域常量，不过要按变量规则来命名也可以。
|
||||
|
||||
|
||||
.. _function-names:
|
||||
|
||||
6.6. 函数命名
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
常规函数使用大小写混合, 取值和设值函数则要求与变量名匹配: ``MyExcitingFunction()``, ``MyExcitingMethod()``, ``my_exciting_member_variable()``, ``set_my_exciting_member_variable()``.
|
||||
|
||||
常规函数:
|
||||
@ -179,6 +185,7 @@
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
名字空间用小写字母命名, 并基于项目名称和目录结构: ``google_awesome_project``.
|
||||
|
||||
关于名字空间的讨论和如何命名, 参考 :ref:`名字空间 <namespaces>` 一节.
|
||||
@ -187,6 +194,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
枚举的命名应当和 :ref:`常量 <constant-names>` 或 :ref:`宏 <macro-names>` 一致: ``kEnumName`` 或是 ``ENUM_NAME``.
|
||||
|
||||
单独的枚举值应该优先采用 :ref:`常量 <constant-names>` 的命名方式. 但 :ref:`宏 <macro-names>` 方式的命名也可以接受. 枚举名 ``UrlTableErrors`` (以及 ``AlternateUrlTableErrors``) 是类型, 所以要用大小写混合的方式.
|
||||
@ -211,6 +219,7 @@
|
||||
~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
你并不打算:ref:`使用宏 <preprocessor-macros>`, 对吧? 如果你一定要用, 像这样命名: ``MY_MACRO_THAT_SCARES_SMALL_CHILDREN``.
|
||||
|
||||
参考:ref:`预处理宏 <preprocessor-macros>`; 通常 *不应该* 使用宏. 如果不得不用, 其命名像枚举命名一样全部大写, 使用下划线::
|
||||
@ -222,20 +231,26 @@
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
如果你命名的实体与已有 C/C++ 实体相似, 可参考现有命名策略.
|
||||
|
||||
``bigopen()``:
|
||||
|
||||
函数名, 参照 ``open()`` 的形式
|
||||
|
||||
``uint``:
|
||||
|
||||
``typedef``
|
||||
|
||||
``bigpos``:
|
||||
|
||||
``struct`` 或 ``class``, 参照 ``pos`` 的形式
|
||||
|
||||
``sparse_hash_map``:
|
||||
|
||||
STL 相似实体; 参照 STL 命名约定
|
||||
|
||||
``LONGLONG_MAX``:
|
||||
|
||||
常量, 如同 ``INT_MAX``
|
||||
|
||||
|
||||
@ -5,6 +5,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
所有按引用传递的参数必须加上 ``const``.
|
||||
|
||||
定义:
|
||||
@ -46,6 +47,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
若要用好函数重载，最好能让读者一看调用点（call site）就胸有成竹，不用花心思猜测调用的重载函数到底是哪一种。该规则适用于构造函数。
|
||||
|
||||
定义:
|
||||
@ -76,6 +78,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
我们不允许使用缺省函数参数，少数极端情况除外。尽可能改用函数重载。
|
||||
|
||||
优点:
|
||||
@ -108,6 +111,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
我们不允许使用变长数组和 ``alloca()``.
|
||||
|
||||
优点:
|
||||
@ -126,6 +130,7 @@
|
||||
~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
我们允许合理的使用友元类及友元函数.
|
||||
|
||||
通常友元应该定义在同一文件内, 避免代码读者跑到其它文件查找使用该私有成员的类. 经常用到友元的一个地方是将 ``FooBuilder`` 声明为 ``Foo`` 的友元, 以便 ``FooBuilder`` 正确构造 ``Foo`` 的内部状态, 而无需将该状态暴露出来. 某些情况下, 将一个单元测试类声明成待测类的友元会很方便.
|
||||
@ -136,6 +141,7 @@
|
||||
~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
我们不使用 C++ 异常.
|
||||
|
||||
优点:
|
||||
@ -181,6 +187,7 @@
|
||||
TODO
|
||||
|
||||
.. tip::
|
||||
|
||||
我们禁止使用 RTTI.
|
||||
|
||||
定义:
|
||||
@ -211,6 +218,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
使用 C++ 的类型转换, 如 ``static_cast<>()``. 不要使用 ``int y = (int)x`` 或 ``int y = int(x)`` 等转换方式;
|
||||
|
||||
定义:
|
||||
@ -239,6 +247,7 @@
|
||||
~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
只在记录日志时使用流.
|
||||
|
||||
定义:
|
||||
@ -291,6 +300,7 @@
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
对于迭代器和其他模板对象使用前缀形式 (``++i``) 的自增, 自减运算符.
|
||||
|
||||
定义:
|
||||
@ -313,6 +323,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
我们强烈建议你在任何可能的情况下都要使用 ``const``. 此外有时改用 C++11 推出的 constexpr 更好。
|
||||
|
||||
定义:
|
||||
@ -349,6 +360,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
在 C++11 里，用 constexpr 来定义真正的常量，或实现常量初始化。
|
||||
|
||||
定义:
|
||||
@ -371,6 +383,7 @@
|
||||
~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
C++ 内建整型中, 仅使用 ``int``. 如果程序中需要不同大小的变量, 可以使用 ``<stdint.h>`` 中长度精确的整型, 如 ``int16_t``.如果您的变量可能不小于 2^31 (2GiB), 就用 64 位变量比如 ``int64_t``. 此外要留意，哪怕您的值并不会超出 int 所能够表示的范围，在计算过程中也可能会溢出。所以拿不准时，干脆用更大的类型。
|
||||
|
||||
定义:
|
||||
@ -415,6 +428,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
代码应该对 64 位和 32 位系统友好. 处理打印, 比较, 结构体对齐时应切记:
|
||||
|
||||
- 对于某些类型, ``printf()`` 的指示符在 32 位和 64 位系统上可移植性不是很好. C99 标准定义了一些可移植的格式化指示符. 不幸的是, MSVC 7.1 并非全部支持, 而且标准中也有所遗漏, 所以有时我们不得不自己定义一个丑陋的版本 (头文件 ``inttypes.h`` 仿标准风格):
|
||||
@ -476,6 +490,7 @@
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
使用宏时要非常谨慎, 尽量以内联函数, 枚举和常量代替之.
|
||||
|
||||
宏意味着你和编译器看到的代码是不同的. 这可能会导致异常行为, 尤其因为宏具有全局作用域.
|
||||
@ -496,6 +511,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
整数用 ``0``, 实数用 ``0.0``, 指针用 ``nullptr`` 或 ``NULL``, 字符 (串) 用 ``'\0'``.
|
||||
|
||||
整数用 ``0``, 实数用 ``0.0``, 这一点是毫无争议的.
|
||||
@ -508,6 +524,7 @@
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
尽可能用 ``sizeof(varname)`` 代替 ``sizeof(type)``.
|
||||
|
||||
使用 ``sizeof(varname)`` 是因为当代码中变量类型改变时会自动更新. 您或许会用 ``sizeof(type)`` 处理不涉及任何变量的代码，比如处理来自外部或内部的数据格式，这时用变量就不合适了。
|
||||
@ -533,6 +550,7 @@
|
||||
~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
用 ``auto`` 绕过烦琐的类型名，只要可读性好就继续用，别用在局部变量之外的地方。
|
||||
|
||||
定义：
|
||||
@ -605,6 +623,7 @@
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
你可以用列表初始化。
|
||||
|
||||
早在 C++03 里，聚合类型（aggregate types）就已经可以被列表初始化了，比如数组和不自带构造函数的结构体：
|
||||
@ -692,6 +711,7 @@
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
适当使用 lambda 表达式。别用默认 lambda 捕获，所有捕获都要显式写出来。
|
||||
|
||||
定义：
|
||||
@ -733,6 +753,7 @@
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
只使用 Boost 中被认可的库.
|
||||
|
||||
定义:
|
||||
@ -785,6 +806,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
适当用 C++11（前身是 C++0x）的库和语言扩展，在贵项目用 C++11 特性前三思可移植性。
|
||||
|
||||
定义：
|
||||
|
||||
@ -7,6 +7,7 @@
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
鼓励在 ``.cc`` 文件内使用匿名名字空间. 使用具名的名字空间时, 其名称可基于项目名或相对路径. 禁止使用 using 指示（using-directive）。禁止使用内联命名空间（inline namespace）。
|
||||
|
||||
定义:
|
||||
@ -160,9 +161,11 @@
|
||||
~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
当公有嵌套类作为接口的一部分时, 虽然可以直接将他们保持在全局作用域中, 但将嵌套类的声明置于:ref:`namespaces`内是更好的选择.
|
||||
|
||||
定义: 在一个类内部定义另一个类; 嵌套类也被称为 *成员类 (member class)*.
|
||||
|
||||
.. code-block:: c++
|
||||
|
||||
class Foo {
|
||||
@ -191,6 +194,7 @@
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
使用静态成员函数或名字空间内的非成员函数, 尽量不要用裸的全局函数.
|
||||
|
||||
优点:
|
||||
@ -213,6 +217,7 @@
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
将函数变量尽可能置于最小作用域内, 并在变量声明时进行初始化.
|
||||
|
||||
C++ 允许在函数的任何位置声明变量. 我们提倡在尽可能小的作用域中声明变量, 离第一次使用越近越好. 这使得代码浏览者更容易定位变量声明的位置, 了解变量的类型和初始值. 特别是，应使用初始化的方式替代声明再赋值, 比如:
|
||||
@ -260,6 +265,7 @@ C++ 允许在函数的任何位置声明变量. 我们提倡在尽可能小的
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. tip::
|
||||
|
||||
禁止使用 ``class`` 类型的静态或全局变量：它们会导致难以发现的 bug 和不确定的构造和析构函数调用顺序。不过 ``constexpr`` 变量除外，毕竟它们又不涉及动态初始化或析构。
|
||||
|
||||
静态生存周期的对象，即包括了全局变量，静态变量，静态类成员变量和函数静态变量，都必须是原生数据类型 (POD : Plain Old Data): 即 int, char 和 float, 以及 POD 类型的指针、数组和结构体。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user