From 34a31e79357b45cc384657f5a60a8e19d530fe35 Mon Sep 17 00:00:00 2001 From: acgtyrant Date: Wed, 29 Jul 2015 19:16:45 +0800 Subject: [PATCH] =?UTF-8?q?=E9=87=8D=E6=8E=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 继续补充遗漏的断行。 统一译者笔记的列表符号为 # 在 tip 后全断行。 --- google-cpp-styleguide/comments.rst | 11 +++++- google-cpp-styleguide/exceptions.rst | 2 + google-cpp-styleguide/formatting.rst | 57 +++++++++++++++++++--------- google-cpp-styleguide/headers.rst | 5 +++ google-cpp-styleguide/magic.rst | 2 + google-cpp-styleguide/naming.rst | 17 ++++++++- google-cpp-styleguide/others.rst | 22 +++++++++++ google-cpp-styleguide/scoping.rst | 6 +++ 8 files changed, 102 insertions(+), 20 deletions(-) diff --git a/google-cpp-styleguide/comments.rst b/google-cpp-styleguide/comments.rst index fecbfd4..89d6141 100644 --- a/google-cpp-styleguide/comments.rst +++ b/google-cpp-styleguide/comments.rst @@ -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`` 的注释，以标记某接口为弃用状态。注释可以放在接口声明前，或者同一行。 diff --git a/google-cpp-styleguide/exceptions.rst b/google-cpp-styleguide/exceptions.rst index 255b399..41ea697 100644 --- a/google-cpp-styleguide/exceptions.rst +++ b/google-cpp-styleguide/exceptions.rst @@ -7,6 +7,7 @@ ~~~~~~~~~~~~~~~~~~~ .. tip:: + 对于现有不符合既定编程风格的代码可以网开一面. 当你修改使用其他风格的代码时, 为了与代码原有风格保持一致可以不使用本指南约定. 如果不放心可以与代码原作者或现在的负责人员商讨, 记住, *一致性* 包括原有的一致性. @@ -17,6 +18,7 @@ ~~~~~~~~~~~~~~~~ .. tip:: + Windows 程序员有自己的编程习惯, 主要源于 Windows 头文件和其它 Microsoft 代码. 我们希望任何人都可以顺利读懂你的代码, 所以针对所有平台的 C++ 编程只给出一个单独的指南. 如果你习惯使用 Windows 编码风格, 这儿有必要重申一下某些你可能会忘记的指南: diff --git a/google-cpp-styleguide/formatting.rst b/google-cpp-styleguide/formatting.rst index d38f343..e2ee23a 100644 --- a/google-cpp-styleguide/formatting.rst +++ b/google-cpp-styleguide/formatting.rst @@ -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:`标准行宽 `, 断行方式要统一一下. 下例中, 逻辑与 (``&&``) 操作符总位于行尾: @@ -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:`类注释 `) 的基本格式如下: @@ -610,6 +626,7 @@ ~~~~~~~~~~~~~~ .. tip:: + 构造函数初始化列表放在同一行或按四格缩进并排几行. 下面两种初始化列表方式都可以接受: @@ -636,6 +653,7 @@ ~~~~~~~~~~~~~~~~~ .. tip:: + 名字空间内容不缩进. :ref:`名字空间 ` 不要增加额外的缩进层次, 例如: @@ -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 正好`有栽过跟头 `_. -* 其实我主张指针／地址操作符与变量名紧邻，``int* a, b`` vs ``int *a, b``, 新手会误以为前者的 ``b`` 是 ``int *`` 变量，但后者就不一样了，高下立判。 -* 在这风格指南里我才刚知道 C++ 原来还有所谓的 `Alternative operator representations `_, 大概没人用吧。 -* 事实上，如果您熟悉英语本身的书写规则，就会发现该风格指南在格式上的规定与英语语法相当一脉相承。比如普通标点符号和单词后面还有文本的话，总会留一个空格；特殊符号与单词之间就不用留了，比如 ``if (true)`` 中的圆括号与 ``true``. +# 80 行限制事实上有助于避免代码可读性失控，比如超多重嵌套块，超多重函数调用等等。 +# Linux 上设置好了 Locale 就几乎一劳永逸设置好所有开发环境的编码，不像奇葩的 Windows. +# Google 强调有一对 if-else 时，不论有没有嵌套，都要有大括号。Apple 正好`有栽过跟头 `_. +# 其实我主张指针／地址操作符与变量名紧邻，``int* a, b`` vs ``int *a, b``, 新手会误以为前者的 ``b`` 是 ``int *`` 变量，但后者就不一样了，高下立判。 +# 在这风格指南里我才刚知道 C++ 原来还有所谓的 `Alternative operator representations `_, 大概没人用吧。 +# 事实上，如果您熟悉英语本身的书写规则，就会发现该风格指南在格式上的规定与英语语法相当一脉相承。比如普通标点符号和单词后面还有文本的话，总会留一个空格；特殊符号与单词之间就不用留了，比如 ``if (true)`` 中的圆括号与 ``true``. diff --git a/google-cpp-styleguide/headers.rst b/google-cpp-styleguide/headers.rst index bbcf594..55405b0 100644 --- a/google-cpp-styleguide/headers.rst +++ b/google-cpp-styleguide/headers.rst @@ -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`` 防止头文件被多重包含, 命名格式当是: ``___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`` 指针. 对参数排序时, 将只输入的参数放在所有输出参数之前. 尤其是不要仅仅因为是新加的参数, 就把它放在最后; 即使是新加的只输入参数也要放在输出参数之前. diff --git a/google-cpp-styleguide/magic.rst b/google-cpp-styleguide/magic.rst index 7521b38..5bb4726 100644 --- a/google-cpp-styleguide/magic.rst +++ b/google-cpp-styleguide/magic.rst @@ -7,6 +7,7 @@ Google 用了很多自己实现的技巧 / 工具使 C++ 代码更加健壮, 我 ~~~~~~~~~~~~~~~~~ .. tip:: + 动态分配出的对象最好有单一且固定的所有主（onwer）, 且通过智能指针传递所有权（ownership）. 定义： @@ -40,6 +41,7 @@ Google 用了很多自己实现的技巧 / 工具使 C++ 代码更加健壮, 我 ~~~~~~~~~~~~ .. tip:: + 使用 ``cpplint.py`` 检查风格错误. ``cpplint.py`` 是一个用来分析源文件, 能检查出多种风格错误的工具. 它不并完美, 甚至还会漏报和误报, 但它仍然是一个非常有用的工具. 在行尾加 ``// NOLINT``, 或在上一行加 ``// NOLINTNEXTLINE``, 可以忽略报错。 diff --git a/google-cpp-styleguide/naming.rst b/google-cpp-styleguide/naming.rst index 11e50b0..35b4b9f 100644 --- a/google-cpp-styleguide/naming.rst +++ b/google-cpp-styleguide/naming.rst @@ -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:`名字空间 ` 一节. @@ -187,6 +194,7 @@ ~~~~~~~~~~~ .. tip:: + 枚举的命名应当和 :ref:`常量 ` 或 :ref:`宏 ` 一致: ``kEnumName`` 或是 ``ENUM_NAME``. 单独的枚举值应该优先采用 :ref:`常量 ` 的命名方式. 但 :ref:`宏 ` 方式的命名也可以接受. 枚举名 ``UrlTableErrors`` (以及 ``AlternateUrlTableErrors``) 是类型, 所以要用大小写混合的方式. @@ -211,6 +219,7 @@ ~~~~~~~~~ .. tip:: + 你并不打算:ref:`使用宏 `, 对吧? 如果你一定要用, 像这样命名: ``MY_MACRO_THAT_SCARES_SMALL_CHILDREN``. 参考:ref:`预处理宏 `; 通常 *不应该* 使用宏. 如果不得不用, 其命名像枚举命名一样全部大写, 使用下划线:: @@ -222,20 +231,26 @@ ~~~~~~~~~~~~~~~~~ .. tip:: + 如果你命名的实体与已有 C/C++ 实体相似, 可参考现有命名策略. ``bigopen()``: + 函数名, 参照 ``open()`` 的形式 ``uint``: + ``typedef`` ``bigpos``: + ``struct`` 或 ``class``, 参照 ``pos`` 的形式 ``sparse_hash_map``: + STL 相似实体; 参照 STL 命名约定 ``LONGLONG_MAX``: + 常量, 如同 ``INT_MAX`` diff --git a/google-cpp-styleguide/others.rst b/google-cpp-styleguide/others.rst index 3171e74..e3db5d5 100644 --- a/google-cpp-styleguide/others.rst +++ b/google-cpp-styleguide/others.rst @@ -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``. 如果程序中需要不同大小的变量, 可以使用 ```` 中长度精确的整型, 如 ``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 特性前三思可移植性。 定义： diff --git a/google-cpp-styleguide/scoping.rst b/google-cpp-styleguide/scoping.rst index d12a8ee..a066aea 100644 --- a/google-cpp-styleguide/scoping.rst +++ b/google-cpp-styleguide/scoping.rst @@ -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 类型的指针、数组和结构体。