mirror of
https://github.com/zh-google-styleguide/zh-google-styleguide.git
synced 2025-02-19 20:50:10 +08:00
yongliang
GitHub
commit
aaf4081692
16
README.rst
16
README.rst
@ -21,24 +21,28 @@ Google 开源项目风格指南——中文版
|
||||
|
||||
英文版项目维护的是在 Google 使用的编程风格指南。如果你正在修改的项目源自 Google，你可能会被引导至英文版项目页面，以了解项目所使用的风格。
|
||||
|
||||
我们已经发布了七份 **中文版** 的风格指南:
|
||||
我们已经发布了 **9** 份 **中文版** 的风格指南:
|
||||
|
||||
#. `Google C++ 风格指南 <http://zh-google-styleguide.readthedocs.org/en/latest/google-cpp-styleguide/>`_
|
||||
#. `Google C++ 风格指南 <https://zh-google-styleguide.readthedocs.org/en/latest/google-cpp-styleguide/>`_
|
||||
|
||||
#. `Google Objective-C 风格指南 <http://zh-google-styleguide.readthedocs.org/en/latest/google-objc-styleguide/>`_
|
||||
#. `Google Objective-C 风格指南 <https://zh-google-styleguide.readthedocs.org/en/latest/google-objc-styleguide/>`_
|
||||
|
||||
#. `Google Python 风格指南 <http://zh-google-styleguide.readthedocs.org/en/latest/google-python-styleguide/>`_
|
||||
#. `Google Python 风格指南 <https://zh-google-styleguide.readthedocs.org/en/latest/google-python-styleguide/>`_
|
||||
|
||||
#. `Google JavaScript 风格指南 <https://zh-google-styleguide.readthedocs.io/en/latest/google-javascript-styleguide/contents/>`_
|
||||
|
||||
#. `Google Shell 风格指南 <http://zh-google-styleguide.readthedocs.org/en/latest/google-shell-styleguide/>`_
|
||||
#. `Google Shell 风格指南 <https://zh-google-styleguide.readthedocs.org/en/latest/google-shell-styleguide/>`_
|
||||
|
||||
#. `Google JSON 风格指南 <https://github.com/darcyliu/google-styleguide/blob/master/JSONStyleGuide.md>`_
|
||||
|
||||
#. `Google TypeScript 风格指南 <https://zh-google-styleguide.readthedocs.io/en/latest/google-typescript-styleguide/contents/>`_
|
||||
|
||||
#. `Google HTML/CSS 风格指南 <https://zh-google-styleguide.readthedocs.io/en/latest/google-html-css-styleguide/contents/>`_
|
||||
|
||||
#. `Google Java 风格指南 <https://zh-google-styleguide.readthedocs.io/en/latest/google-java-styleguide/contents/>`_
|
||||
|
||||
中文版项目采用 reStructuredText 纯文本标记语法，并使用 Sphinx 生成 HTML / CHM / PDF 等文档格式。
|
||||
|
||||
* 英文版项目还包含 `cpplint <https://github.com/google/styleguide/tree/gh-pages/cpplint>`_ ——一个用来帮助适应风格准则的工具，以及 `google-c-style.el <https://raw.githubusercontent.com/google/styleguide/gh-pages/google-c-style.el>`_，Google 风格的 Emacs 配置文件。
|
||||
|
||||
* 另外，招募志愿者翻译 `XML Document Format Style Guide <http://google.github.io/styleguide/xmlstyle.html>`_ ，有意者请联系 `Yang.Y <https://github.com/yangyubo>`_ 。
|
||||
* 另外，招募志愿者翻译 `XML Document Format Style Guide <https://google.github.io/styleguide/xmlstyle.html>`_ ，有意者请联系 `Yang.Y <https://github.com/yangyubo>`_ 。
|
||||
|
||||
@ -252,7 +252,7 @@ C++ 中 ``struct`` 和 ``class`` 关键字的含义几乎一样. 我们自己为
|
||||
|
||||
**定义**
|
||||
|
||||
用户可以使用 ``operator`` 关键字来 `重载内置运算符 <http://en.cppreference.com/w/cpp/language/operators>`_ , 前提是其中一个参数是用户自定义类型. 用户还可以使用 ``operator""`` 定义一类新的字面量, 或者定义类型转换函数 (例如 ``operator bool()``).
|
||||
用户可以使用 ``operator`` 关键字来 `重载内置运算符 <https://en.cppreference.com/w/cpp/language/operators>`_ , 前提是其中一个参数是用户自定义类型. 用户还可以使用 ``operator""`` 定义一类新的字面量, 或者定义类型转换函数 (例如 ``operator bool()``).
|
||||
|
||||
**优点**
|
||||
|
||||
|
||||
@ -862,9 +862,9 @@ Lambda 表达式对形参和函数体的格式化和其他函数一致; 捕获
|
||||
|
||||
#. 80 行限制事实上有助于避免代码可读性失控, 比如超多重嵌套块, 超多重函数调用等等.
|
||||
#. Linux 上设置好了 Locale 就几乎一劳永逸设置好所有开发环境的编码, 不像奇葩的 Windows.
|
||||
#. Google 强调有一对 if-else 时, 不论有没有嵌套, 都要有大括号. Apple 正好 `有栽过跟头 <http://coolshell.cn/articles/11112.html>`_ .
|
||||
#. Google 强调有一对 if-else 时, 不论有没有嵌套, 都要有大括号. Apple 正好 `有栽过跟头 <https://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>`_, 大概没人用吧.
|
||||
#. 在这风格指南里我才刚知道 C++ 原来还有所谓的 `Alternative operator representations <https://en.cppreference.com/w/cpp/language/operator_alternative>`_, 大概没人用吧.
|
||||
#. 注意构造函数初始值列表（Constructer Initializer List）与列表初始化（Initializer List）是两码事, 我就差点混淆了它们的翻译.
|
||||
#. 事实上, 如果您熟悉英语本身的书写规则, 就会发现该风格指南在格式上的规定与英语语法相当一脉相承. 比如普通标点符号和单词后面还有文本的话, 总会留一个空格; 特殊符号与单词之间就不用留了, 比如 ``if (true)`` 中的圆括号与 ``true``.
|
||||
#. 本风格指南没有明确规定 void 函数里要不要用 return 语句, 不过就 Google 开源项目 leveldb 并没有写; 此外从 `Is a blank return statement at the end of a function whos return type is void necessary? <http://stackoverflow.com/questions/9316717/is-a-blank-return-statement-at-the-end-of-a-function-whos-return-type-is-void-ne>`_ 来看, ``return;`` 比 ``return ;`` 更约定俗成（事实上 cpplint 会对后者报错, 指出分号前有多余的空格）, 且可用来提前跳出函数栈.
|
||||
#. 本风格指南没有明确规定 void 函数里要不要用 return 语句, 不过就 Google 开源项目 leveldb 并没有写; 此外从 `Is a blank return statement at the end of a function whos return type is void necessary? <https://stackoverflow.com/questions/9316717/is-a-blank-return-statement-at-the-end-of-a-function-whos-return-type-is-void-ne>`_ 来看, ``return;`` 比 ``return ;`` 更约定俗成（事实上 cpplint 会对后者报错, 指出分号前有多余的空格）, 且可用来提前跳出函数栈.
|
||||
|
||||
@ -10,15 +10,17 @@
|
||||
|
||||
**说明**
|
||||
|
||||
C++ 函数由返回值提供天然的输出， 有时也通过输出参数（或输入/输出参数）提供. 我们倾向于使用返回值而不是输出参数： 它们提高了可读性， 并且通常提供相同或更好的性能.
|
||||
C/C++ 函数的输出自然通过返回值提供，有时通过输出参数（或输入/输出参数）提供. 我们更倾向于使用返回值而不是输出参数：它们可以提高可读性，并且通常提供相同或更好的性能。
|
||||
|
||||
C/C++ 中的函数参数或者是函数的输入, 或者是函数的输出, 或兼而有之. 非可选输入参数通常是值参或 ``const`` 引用, 非可选输出参数或输入/输出参数通常应该是引用 （不能为空）. 对于可选的参数， 通常使用 ``std::optional`` 来表示可选的按值输入， 使用 ``const`` 指针来表示可选的其他输入． 使用非常量指针来表示可选输出和可选输入/输出参数．
|
||||
更喜欢按值返回，或者如果失败，则通过引用返回。避免返回原始指针，除非它可以为空。
|
||||
|
||||
避免定义需要 ``const`` 引用参数去超出生命周期的函数， 因为 ``const`` 引用参数与临时变量绑定． 相反， 要找到某种方法来消除生命周期要求 （例如， 通过复制参数）， 或者通过 ``const`` 指针传递它并记录生命周期和非空要求.
|
||||
C/C++ 中的参数可以是函数的输入、函数的输出，或者两者兼而有之。非可选输入参数通常应该是值或 ``const`` 引用，而非可选输出和输入/输出参数通常应该是引用（不能为空）。通常，使用 ``std：：optional`` 来表示可选的按值输入，并在非可选形式使用引用时使用 ``const`` 指针。使用非 ``const`` 指针来表示可选输出和可选输入/输出参数。
|
||||
|
||||
在排序函数参数时， 将所有输入参数放在所有输出参数之前. 特别要注意, 在加入新参数时不要因为它们是新参数就置于参数列表最后, 而是仍然要按照前述的规则, 即将新的输入参数也置于输出参数之前.
|
||||
避免定义需要 ``const`` 引用参数才能延长调用期限的函数。在某些情况下， ``const`` 引用参数可能会绑定到临时参数，从而导致生命周期错误。相反，请找到一种方法来消除生命周期要求（例如，通过复制参数），或者通过 ``const`` 指针传递保留的参数并记录生命周期和非空要求。
|
||||
|
||||
这并非一个硬性规定. 输入/输出参数 (通常是类或结构体) 让这个问题变得复杂. 并且, 有时候为了其他函数保持一致, 你可能不得不有所变通.
|
||||
对函数参数进行排序时，请将所有仅输入参数放在任何输出参数之前。特别要注意，不要仅仅因为新参数是新参数而将新参数添加到函数末尾，而是仍然要按照前述的规则，即将新的输入参数也置于输出参数之前。
|
||||
|
||||
这不是一个硬性规定。输入和输出的参数会让局面变得混乱，而且一如既往，与相关功能的一致性可能需要您改变规则。可变函数还可能需要异常的参数排序。
|
||||
|
||||
4.2. 编写简短函数
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -17,16 +17,16 @@
|
||||
|
||||
.. line-block::
|
||||
|
||||
`YuleFox <http://www.yulefox.com>`_
|
||||
`YuleFox <https://www.yulefox.com>`_
|
||||
`Yang.Y <https://github.com/yangyubo>`_
|
||||
`acgtyrant <http://acgtyrant.com>`_
|
||||
`lilinsanity <http://github.com/lilinsanity>`_
|
||||
`acgtyrant <https://acgtyrant.com>`_
|
||||
`lilinsanity <https://github.com/lilinsanity>`_
|
||||
`楼宇 <https://github.com/LouYu2015>`_
|
||||
|
||||
:项目主页:
|
||||
|
||||
- `Google Style Guide <http://google-styleguide.googlecode.com>`_
|
||||
- `Google 开源项目风格指南 - 中文版 <http://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
- `Google Style Guide <https://google-styleguide.googlecode.com>`_
|
||||
- `Google 开源项目风格指南 - 中文版 <https://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
|
||||
译者前言
|
||||
--------------------
|
||||
@ -55,11 +55,11 @@ Google 经常会发布一些开源项目, 意味着会接受来自其他代码
|
||||
|
||||
- 2009-06 3.133 : YuleFox 的 1.0 版已经相当完善, 但原版在近一年的时间里, 其规范也发生了一些变化.
|
||||
|
||||
Yang.Y 与 YuleFox 一拍即合, 以项目的形式来延续中文版 : `Google 开源项目风格指南 - 中文版项目 <http://github.com/yangyubo/zh-google-styleguide>`_.
|
||||
Yang.Y 与 YuleFox 一拍即合, 以项目的形式来延续中文版 : `Google 开源项目风格指南 - 中文版项目 <https://github.com/yangyubo/zh-google-styleguide>`_.
|
||||
|
||||
主要变化是同步到 3.133 最新英文版本, 做部分勘误和改善可读性方面的修改, 并改进排版效果. Yang.Y 重新翻修, YuleFox 做后续评审.
|
||||
|
||||
- 2008-07 1.0 : 出自 `YuleFox 的 Blog <http://www.yulefox.com/?p=207>`_, 很多地方摘录的也是该版本.
|
||||
- 2008-07 1.0 : 出自 `YuleFox 的 Blog <https://www.yulefox.com/?p=207>`_, 很多地方摘录的也是该版本.
|
||||
|
||||
以下是正文.
|
||||
|
||||
|
||||
@ -14,7 +14,7 @@ Google 用了很多自己实现的技巧 / 工具使 C++ 代码更加健壮, 我
|
||||
|
||||
所有权是一种登记／管理动态内存和其它资源的技术. 动态分配对象的所有主是一个对象或函数, 后者负责确保当前者无用时就自动销毁前者. 所有权有时可以共享, 此时就由最后一个所有主来负责销毁它. 甚至也可以不用共享, 在代码中直接把所有权传递给其它对象.
|
||||
|
||||
智能指针是一个通过重载 ``*`` 和 ``->`` 运算符以表现得如指针一样的类. 智能指针类型被用来自动化所有权的登记工作, 来确保执行销毁义务到位. `std::unique_ptr <http://en.cppreference.com/w/cpp/memory/unique_ptr>`_ 是 C++11 新推出的一种智能指针类型, 用来表示动态分配出的对象的独一无二的所有权; 当 ``std::unique_ptr`` 离开作用域时, 对象就会被销毁. ``std::unique_ptr`` 不能被复制, 但可以把它移动（move）给新所有主. `std::shared_ptr <http://en.cppreference.com/w/cpp/memory/shared_ptr>`_ 同样表示动态分配对象的所有权, 但可以被共享, 也可以被复制; 对象的所有权由所有复制者共同拥有, 最后一个复制者被销毁时, 对象也会随着被销毁.
|
||||
智能指针是一个通过重载 ``*`` 和 ``->`` 运算符以表现得如指针一样的类. 智能指针类型被用来自动化所有权的登记工作, 来确保执行销毁义务到位. `std::unique_ptr <https://en.cppreference.com/w/cpp/memory/unique_ptr>`_ 是 C++11 新推出的一种智能指针类型, 用来表示动态分配出的对象的独一无二的所有权; 当 ``std::unique_ptr`` 离开作用域时, 对象就会被销毁. ``std::unique_ptr`` 不能被复制, 但可以把它移动（move）给新所有主. `std::shared_ptr <https://en.cppreference.com/w/cpp/memory/shared_ptr>`_ 同样表示动态分配对象的所有权, 但可以被共享, 也可以被复制; 对象的所有权由所有复制者共同拥有, 最后一个复制者被销毁时, 对象也会随着被销毁.
|
||||
|
||||
**> 优点**
|
||||
|
||||
@ -74,7 +74,7 @@ Google 用了很多自己实现的技巧 / 工具使 C++ 代码更加健壮, 我
|
||||
|
||||
``cpplint.py`` 是一个用来分析源文件, 能检查出多种风格错误的工具. 它不并完美, 甚至还会漏报和误报, 但它仍然是一个非常有用的工具. 在行尾加 ``// NOLINT``, 或在上一行加 ``// NOLINTNEXTLINE``, 可以忽略报错.
|
||||
|
||||
某些项目会指导你如何使用他们的项目工具运行 ``cpplint.py``. 如果你参与的项目没有提供, 你可以单独下载 `cpplint.py <http://github.com/google/styleguide/blob/gh-pages/cpplint/cpplint.py>`_.
|
||||
某些项目会指导你如何使用他们的项目工具运行 ``cpplint.py``. 如果你参与的项目没有提供, 你可以单独下载 `cpplint.py <https://github.com/google/styleguide/blob/gh-pages/cpplint/cpplint.py>`_.
|
||||
|
||||
|
||||
译者（acgtyrant）笔记
|
||||
|
||||
@ -161,7 +161,7 @@ C++ 文件要以 ``.cc`` 结尾, 头文件以 ``.h`` 结尾. 专门插入文本
|
||||
|
||||
**说明**
|
||||
|
||||
所有具有静态存储类型的变量 (例如静态变量或全局变量, 参见 `存储类型 <http://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration>`_) 都应当以此方式命名. 对于其他存储类型的变量, 如自动变量等, 这条规则是可选的. 如果不采用这条规则, 就按照一般的变量命名规则.
|
||||
所有具有静态存储类型的变量 (例如静态变量或全局变量, 参见 `存储类型 <https://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration>`_) 都应当以此方式命名. 对于其他存储类型的变量, 如自动变量等, 这条规则是可选的. 如果不采用这条规则, 就按照一般的变量命名规则.
|
||||
|
||||
.. _function-names:
|
||||
|
||||
|
||||
@ -629,7 +629,7 @@
|
||||
auto x(3); // 圆括号。
|
||||
auto y{3}; // 大括号。
|
||||
|
||||
它们不是同一回事——``x`` 是 ``int``, ``y`` 则是 ``std::initializer_list<int>``. 其它一般不可见的代理类型（acgtyrant 注：normally-invisible proxy types, 它涉及到 C++ 鲜为人知的坑：`Why is vector<bool> not a STL container? <http://stackoverflow.com/a/17794965/1546088>`_）也有大同小异的陷阱。
|
||||
它们不是同一回事——``x`` 是 ``int``, ``y`` 则是 ``std::initializer_list<int>``. 其它一般不可见的代理类型（acgtyrant 注：normally-invisible proxy types, 它涉及到 C++ 鲜为人知的坑：`Why is vector<bool> not a STL container? <https://stackoverflow.com/a/17794965/1546088>`_）也有大同小异的陷阱。
|
||||
|
||||
如果在接口里用 ``auto``, 比如声明头文件里的一个常量，那么只要仅仅因为程序员一时修改其值而导致类型变化的话——API 要翻天覆地了。
|
||||
|
||||
@ -882,7 +882,7 @@
|
||||
|
||||
定义:
|
||||
|
||||
`Boost 库集 <http://www.boost.org/>`_ 是一个广受欢迎, 经过同行鉴定, 免费开源的 C++ 库集.
|
||||
`Boost 库集 <https://www.boost.org/>`_ 是一个广受欢迎, 经过同行鉴定, 免费开源的 C++ 库集.
|
||||
|
||||
优点:
|
||||
|
||||
@ -896,35 +896,35 @@
|
||||
|
||||
为了向阅读和维护代码的人员提供更好的可读性, 我们只允许使用 Boost 一部分经认可的特性子集. 目前允许使用以下库:
|
||||
|
||||
- `Call Traits <http://www.boost.org/doc/libs/1_58_0/libs/utility/call_traits.htm>`_ : ``boost/call_traits.hpp``
|
||||
- `Call Traits <https://www.boost.org/doc/libs/1_58_0/libs/utility/call_traits.htm>`_ : ``boost/call_traits.hpp``
|
||||
|
||||
- `Compressed Pair <http://www.boost.org/libs/utility/compressed_pair.htm>`_ : ``boost/compressed_pair.hpp``
|
||||
- `Compressed Pair <https://www.boost.org/libs/utility/compressed_pair.htm>`_ : ``boost/compressed_pair.hpp``
|
||||
|
||||
- `<The Boost Graph Library (BGL) <http://www.boost.org/doc/libs/1_58_0/libs/graph/doc/index.html>`_ : ``boost/graph``, except serialization (``adj_list_serialize.hpp``) and parallel/distributed algorithms and data structures(``boost/graph/parallel/*`` and ``boost/graph/distributed/*``)
|
||||
- `<The Boost Graph Library (BGL) <https://www.boost.org/doc/libs/1_58_0/libs/graph/doc/index.html>`_ : ``boost/graph``, except serialization (``adj_list_serialize.hpp``) and parallel/distributed algorithms and data structures(``boost/graph/parallel/*`` and ``boost/graph/distributed/*``)
|
||||
|
||||
- `Property Map <http://www.boost.org/libs/property_map/>`_ : ``boost/property_map.hpp``
|
||||
- `Property Map <https://www.boost.org/libs/property_map/>`_ : ``boost/property_map.hpp``
|
||||
|
||||
- The part of `Iterator <http://www.boost.org/libs/iterator/>`_ that deals with defining iterators: ``boost/iterator/iterator_adaptor.hpp``, ``boost/iterator/iterator_facade.hpp``, and ``boost/function_output_iterator.hpp``
|
||||
- The part of `Iterator <https://www.boost.org/libs/iterator/>`_ that deals with defining iterators: ``boost/iterator/iterator_adaptor.hpp``, ``boost/iterator/iterator_facade.hpp``, and ``boost/function_output_iterator.hpp``
|
||||
|
||||
- The part of `Polygon <http://www.boost.org/libs/polygon/>`_ that deals with Voronoi diagram construction and doesn't depend on the rest of Polygon: ``boost/polygon/voronoi_builder.hpp``, ``boost/polygon/voronoi_diagram.hpp``, and ``boost/polygon/voronoi_geometry_type.hpp``
|
||||
- The part of `Polygon <https://www.boost.org/libs/polygon/>`_ that deals with Voronoi diagram construction and doesn't depend on the rest of Polygon: ``boost/polygon/voronoi_builder.hpp``, ``boost/polygon/voronoi_diagram.hpp``, and ``boost/polygon/voronoi_geometry_type.hpp``
|
||||
|
||||
- `Bimap <http://www.boost.org/libs/bimap/>`_ : ``boost/bimap``
|
||||
- `Bimap <https://www.boost.org/libs/bimap/>`_ : ``boost/bimap``
|
||||
|
||||
- `Statistical Distributions and Functions <http://www.boost.org/libs/math/doc/html/dist.html>`_ : ``boost/math/distributions``
|
||||
- `Statistical Distributions and Functions <https://www.boost.org/libs/math/doc/html/dist.html>`_ : ``boost/math/distributions``
|
||||
|
||||
- `Multi-index <http://www.boost.org/libs/multi_index/>`_ : ``boost/multi_index``
|
||||
- `Multi-index <https://www.boost.org/libs/multi_index/>`_ : ``boost/multi_index``
|
||||
|
||||
- `Heap <http://www.boost.org/libs/heap/>`_ : ``boost/heap``
|
||||
- `Heap <https://www.boost.org/libs/heap/>`_ : ``boost/heap``
|
||||
|
||||
- The flat containers from `Container <http://www.boost.org/libs/container/>`_: ``boost/container/flat_map``, and ``boost/container/flat_set``
|
||||
- The flat containers from `Container <https://www.boost.org/libs/container/>`_: ``boost/container/flat_map``, and ``boost/container/flat_set``
|
||||
|
||||
我们正在积极考虑增加其它 Boost 特性, 所以列表中的规则将不断变化.
|
||||
|
||||
以下库可以用，但由于如今已经被 C++ 11 标准库取代，不再鼓励：
|
||||
|
||||
- `Pointer Container <http://www.boost.org/libs/ptr_container/>`_ : ``boost/ptr_container``, 改用 `std::unique_ptr <http://en.cppreference.com/w/cpp/memory/unique_ptr>`_
|
||||
- `Pointer Container <https://www.boost.org/libs/ptr_container/>`_ : ``boost/ptr_container``, 改用 `std::unique_ptr <https://en.cppreference.com/w/cpp/memory/unique_ptr>`_
|
||||
|
||||
- `Array <http://www.boost.org/libs/array/>`_ : ``boost/array.hpp``, 改用 `std::array <http://en.cppreference.com/w/cpp/container/array>`_
|
||||
- `Array <https://www.boost.org/libs/array/>`_ : ``boost/array.hpp``, 改用 `std::array <https://en.cppreference.com/w/cpp/container/array>`_
|
||||
|
||||
6.23. C++11
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -959,14 +959,14 @@
|
||||
译者（acgtyrant）笔记
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
#. 实际上，`缺省参数会改变函数签名的前提是改变了它接收的参数数量 <http://www.zhihu.com/question/24439516/answer/27858964>`_，比如把 ``void a()`` 改成 ``void a(int b = 0)``, 开发者改变其代码的初衷也许是，在不改变「代码兼容性」的同时，又提供了可选 int 参数的余地，然而这终究会破坏函数指针上的兼容性，毕竟函数签名确实变了。
|
||||
#. 实际上，`缺省参数会改变函数签名的前提是改变了它接收的参数数量 <https://www.zhihu.com/question/24439516/answer/27858964>`_，比如把 ``void a()`` 改成 ``void a(int b = 0)``, 开发者改变其代码的初衷也许是，在不改变「代码兼容性」的同时，又提供了可选 int 参数的余地，然而这终究会破坏函数指针上的兼容性，毕竟函数签名确实变了。
|
||||
#. 此外把自带缺省参数的函数地址赋值给指针时，会丢失缺省参数信息。
|
||||
#. 我还发现 `滥用缺省参数会害得读者光只看调用代码的话，会误以为其函数接受的参数数量比实际上还要少。 <http://www.zhihu.com/question/24439516/answer/27896004>`_
|
||||
#. 我还发现 `滥用缺省参数会害得读者光只看调用代码的话，会误以为其函数接受的参数数量比实际上还要少。 <https://www.zhihu.com/question/24439516/answer/27896004>`_
|
||||
#. ``friend`` 实际上只对函数／类赋予了对其所在类的访问权限，并不是有效的声明语句。所以除了在头文件类内部写 friend 函数／类，还要在类作用域之外正式地声明一遍，最后在对应的 ``.cc`` 文件加以定义。
|
||||
#. 本风格指南都强调了「友元应该定义在同一文件内，避免代码读者跑到其它文件查找使用该私有成员的类」。那么可以把其声明放在类声明所在的头文件，定义也放在类定义所在的文件。
|
||||
#. 由于友元函数／类并不是类的一部分，自然也不会是类可调用的公有接口，于是我主张全集中放在类的尾部，即的数据成员之后，参考 :ref:`声明顺序 <declaration-order>` 。
|
||||
#. `对使用 C++ 异常处理应具有怎样的态度？ <http://www.zhihu.com/question/22889420>`_ 非常值得一读。
|
||||
#. `对使用 C++ 异常处理应具有怎样的态度？ <https://www.zhihu.com/question/22889420>`_ 非常值得一读。
|
||||
#. 注意初始化 const 对象时，必须在初始化的同时值初始化。
|
||||
#. 用断言代替无符号整型类型，深有启发。
|
||||
#. auto 在涉及迭代器的循环语句里挺常用。
|
||||
#. `Should the trailing return type syntax style become the default for new C++11 programs? <http://stackoverflow.com/questions/11215227/should-the-trailing-return-type-syntax-style-become-the-default-for-new-c11-pr>`_ 讨论了 auto 与尾置返回类型一起用的全新编码风格，值得一看。
|
||||
#. `Should the trailing return type syntax style become the default for new C++11 programs? <https://stackoverflow.com/questions/11215227/should-the-trailing-return-type-syntax-style-become-the-default-for-new-c11-pr>`_ 讨论了 auto 与尾置返回类型一起用的全新编码风格，值得一看。
|
||||
|
||||
@ -268,7 +268,7 @@
|
||||
|
||||
.. tip::
|
||||
|
||||
禁止使用 `静态储存周期 (static storage duration) <http://zh.cppreference.com/w/cpp/language/storage_duration#.E5.AD.98.E5.82.A8.E6.9C.9F>`_ 的变量, 除非它们可以 `平凡地析构 (trivially destructible) <https://zh.cppreference.com/w/cpp/types/is_destructible>`_. 简单来说, 就是析构函数 (destructor) 不会做任何事情, 包括成员和基类 (base) 的析构函数. 正式地说, 就是这一类型 (type) 没有用户定义的析构函数或虚析构函数 (virtual destructor), 且所有成员和基类也能平凡地析构. 函数的局部静态变量可以动态地初始化 (dynamic initialization) . 除了少数情况外, 不推荐动态初始化静态类成员变量或命名空间内的变量. 详情参见下文.
|
||||
禁止使用 `静态储存周期 (static storage duration) <https://zh.cppreference.com/w/cpp/language/storage_duration#.E5.AD.98.E5.82.A8.E6.9C.9F>`_ 的变量, 除非它们可以 `平凡地析构 (trivially destructible) <https://zh.cppreference.com/w/cpp/types/is_destructible>`_. 简单来说, 就是析构函数 (destructor) 不会做任何事情, 包括成员和基类 (base) 的析构函数. 正式地说, 就是这一类型 (type) 没有用户定义的析构函数或虚析构函数 (virtual destructor), 且所有成员和基类也能平凡地析构. 函数的局部静态变量可以动态地初始化 (dynamic initialization) . 除了少数情况外, 不推荐动态初始化静态类成员变量或命名空间内的变量. 详情参见下文.
|
||||
|
||||
作为经验之谈: 若只看全局变量的声明, 如果该语句可以作为常量表达式 (constexpr), 则满足以上要求.
|
||||
|
||||
|
||||
@ -26,7 +26,7 @@ css文件书写按字母顺序排列的方式，容易记忆和维护，以达
|
||||
|
||||
缩进块内容。
|
||||
|
||||
将包括嵌套及声明的 `块内容 <http://www.w3.org/TR/CSS21/syndata.html#block>`_ 进行缩进，以体现层次并提高可读性。
|
||||
将包括嵌套及声明的 `块内容 <https://www.w3.org/TR/CSS21/syndata.html#block>`_ 进行缩进，以体现层次并提高可读性。
|
||||
|
||||
.. code-block:: css
|
||||
|
||||
@ -84,7 +84,7 @@ CSS属性名结束
|
||||
|
||||
在选择器和后面的声明块之间使用一个空格。
|
||||
|
||||
最后一个选择器与表示 `声名块 <http://www.w3.org/TR/CSS21/syndata.html#rule-sets>`_ 开始的左大花括号在同行，中间有一个字符空格。
|
||||
最后一个选择器与表示 `声名块 <https://www.w3.org/TR/CSS21/syndata.html#rule-sets>`_ 开始的左大花括号在同行，中间有一个字符空格。
|
||||
|
||||
表示开始的左大花括号和选择器在同行。
|
||||
|
||||
@ -157,7 +157,7 @@ CSS引号
|
||||
|
||||
在属性选择器及属性值中使用单引号（''）而不是双引号（""）。在 ``url（）`` 中不要使用引号。
|
||||
|
||||
特例：如果你确实需要定义 ``@charset`` ，由于 `不允许使用单引号 <http://www.w3.org/TR/CSS21/syndata.html#charset>`_ ，故请使用双引号。
|
||||
特例：如果你确实需要定义 ``@charset`` ，由于 `不允许使用单引号 <https://www.w3.org/TR/CSS21/syndata.html#charset>`_ ，故请使用双引号。
|
||||
|
||||
.. code-block:: css
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ CSS有效性
|
||||
|
||||
使用有效的CSS代码，除非在处理css验证器bug或者是专有的语法时。
|
||||
|
||||
使用诸如 `W3C CSS validator <http://jigsaw.w3.org/css-validator/>`_ 等工具验证测试。
|
||||
使用诸如 `W3C CSS validator <https://jigsaw.w3.org/css-validator/>`_ 等工具验证测试。
|
||||
|
||||
使用有效的CSS代码是一个可衡量CSS代码质量的指标，可帮你找出不起作用可被删除的CSS代码，从而确保CSS的合理使用。
|
||||
|
||||
@ -70,7 +70,7 @@ ID和class命名要尽可能简短，但必要的话就别怕长。
|
||||
|
||||
除了必要情况下（例如辅助的类），不要将元素与id或class名称结合做为选择器。
|
||||
|
||||
避免不必要的祖先选择器也是出于 `性能原因 <http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/>`_ 的考虑。
|
||||
避免不必要的祖先选择器也是出于 `性能原因 <https://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/>`_ 的考虑。
|
||||
|
||||
.. code-block:: css
|
||||
|
||||
@ -87,7 +87,7 @@ ID和class命名要尽可能简短，但必要的话就别怕长。
|
||||
|
||||
尽可能使用简写的属性书写方式。
|
||||
|
||||
CSS提供了多种属性 `简写 <http://www.w3.org/TR/CSS21/about.html#shorthand>`_ 的方式（如 ``font`` ），即使只显式设置一个值，也应该尽可能地使用。
|
||||
CSS提供了多种属性 `简写 <https://www.w3.org/TR/CSS21/about.html#shorthand>`_ 的方式（如 ``font`` ），即使只显式设置一个值，也应该尽可能地使用。
|
||||
|
||||
使用简写属性有助于提高代码效率及可读性。
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@
|
||||
|
||||
在HTML模板和文档中使用 ``<meta charset=”utf-8”>`` 指定编码。不需要为样式表指定编码，它默认是UTF-8。
|
||||
|
||||
（想了解更多关于应该何时并如何指定编码，请查看 `Handling character encodings in HTML and CSS <http://www.w3.org/International/tutorials/tutorial-char-enc/>`_）
|
||||
（想了解更多关于应该何时并如何指定编码，请查看 `Handling character encodings in HTML and CSS <https://www.w3.org/International/tutorials/tutorial-char-enc/>`_）
|
||||
|
||||
注释
|
||||
--------
|
||||
|
||||
@ -12,7 +12,7 @@
|
||||
.. code-block:: html
|
||||
|
||||
<!-- 不推荐 -->
|
||||
<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||||
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||||
|
||||
<!-- 推荐 -->
|
||||
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||||
@ -21,7 +21,7 @@
|
||||
|
||||
/* 不推荐 */
|
||||
.example {
|
||||
background: url(http://www.google.com/images/example);
|
||||
background: url(https://www.google.com/images/example);
|
||||
}
|
||||
|
||||
/* 推荐 */
|
||||
|
||||
@ -8,7 +8,7 @@ HTML样式规则
|
||||
|
||||
HTML5（HTML语法）是所有HTML文档的首选： ``<!DOCTYPE html>`` 。
|
||||
|
||||
（推荐使用HTML，即text/html。不要使用XHTML。XHTML，即 `application/xhtml+xml <http://hixie.ch/advocacy/xhtml>`_，缺乏浏览器和基础结构的支持，并且优化的空间比HTML小。）
|
||||
（推荐使用HTML，即text/html。不要使用XHTML。XHTML，即 `application/xhtml+xml <https://hixie.ch/advocacy/xhtml>`_，缺乏浏览器和基础结构的支持，并且优化的空间比HTML小。）
|
||||
虽然HTML闭合标签没有问题，但是不要自闭合空标签。即写 ``<br>`` 而不是 ``<br />`` 。
|
||||
|
||||
|
||||
@ -19,7 +19,7 @@ HTML合法性
|
||||
|
||||
使用合法的HTML代码，除非由于文件大小导致的不可达到的性能目标而不能使用。
|
||||
|
||||
利用已用工具对合法性进行测试，例如 `W3C HTML validator <http://validator.w3.org/nu/>`_。
|
||||
利用已用工具对合法性进行测试，例如 `W3C HTML validator <https://validator.w3.org/nu/>`_。
|
||||
|
||||
使用合法的HTML是一个可度量的基准质量属性，该属性有助于了解技术需求和约束，从而确保合理的HTML使用。
|
||||
|
||||
@ -129,7 +129,7 @@ HTML合法性
|
||||
|
||||
省略可选的标签（可选）。
|
||||
|
||||
为了优化文件大小和可扫描，考虑省略可选标签。 `HTML5规范 <http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission>`_ 定义了哪些标签可以被省略。
|
||||
为了优化文件大小和可扫描，考虑省略可选标签。 `HTML5规范 <https://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission>`_ 定义了哪些标签可以被省略。
|
||||
|
||||
（这种方法可能要求一段宽限期去建立一个更加广泛的准则，因为它和Web开发人员通常所了解的有着显著不同。考虑到一致性和简单性，最好省略所有可选标签。）
|
||||
|
||||
@ -158,7 +158,7 @@ type属性
|
||||
|
||||
引用样式表（除非不是使用CSS）和脚本（除非不是使用JavaScript）不要使用type属性。
|
||||
|
||||
HTML5将 `text/css <http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type>`_ 和 `text/javascript <http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type>`_ 设置为默认值，在这种情况下指定type属性并不必要。甚至同样兼容老版本的浏览器。
|
||||
HTML5将 `text/css <https://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type>`_ 和 `text/javascript <https://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type>`_ 设置为默认值，在这种情况下指定type属性并不必要。甚至同样兼容老版本的浏览器。
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
|
||||
16
google-html-css-styleguide/index.rst
Normal file
16
google-html-css-styleguide/index.rst
Normal file
@ -0,0 +1,16 @@
|
||||
0. 扉页
|
||||
============
|
||||
|
||||
:原作者:
|
||||
.. line-block::
|
||||
|
||||
详细作者列表请参见英文原版的 Git 仓库.
|
||||
|
||||
:翻译:
|
||||
.. line-block::
|
||||
|
||||
- `Google 开源项目风格指南 - 中文版 <https://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
|
||||
:项目主页:
|
||||
|
||||
- `Google Style Guide <https://google-styleguide.googlecode.com>`_
|
||||
@ -15,5 +15,5 @@
|
||||
|
||||
:项目主页:
|
||||
|
||||
- `Google Style Guide <http://google-styleguide.googlecode.com>`_
|
||||
- `Google 开源项目风格指南 - 中文版 <http://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
- `Google Style Guide <https://google-styleguide.googlecode.com>`_
|
||||
- `Google 开源项目风格指南 - 中文版 <https://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
|
||||
17
google-javascript-styleguide/index.rst
Normal file
17
google-javascript-styleguide/index.rst
Normal file
@ -0,0 +1,17 @@
|
||||
0. 扉页
|
||||
============
|
||||
|
||||
:原作者:
|
||||
.. line-block::
|
||||
|
||||
详细作者列表请参见英文原版的 Git 仓库.
|
||||
|
||||
:翻译:
|
||||
.. line-block::
|
||||
|
||||
- `Google 开源项目风格指南 - 中文版 <https://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
|
||||
:项目主页:
|
||||
|
||||
- `Google Style Guide <https://google-styleguide.googlecode.com>`_
|
||||
|
||||
@ -150,7 +150,7 @@ js语句要求以分号结尾，除非能够正确地推断分号的位置。在
|
||||
function foo() {}
|
||||
}
|
||||
|
||||
虽然大多数脚本引擎支持功能区块内声明，但ECMAScript并未认可（见 `ECMA-262 <http://www.ecma-international.org/publications/standards/Ecma-262.htm>`_ ，第13条和第14）。若与他人的及EcmaScript所建议的不一致，即可视为不好的实现方式。ECMAScript只允许函数声明语句列表, 在根语句列表脚本或者函数。相反，使用一个变量初始化函数表达式在块内定义一个函数块：
|
||||
虽然大多数脚本引擎支持功能区块内声明，但ECMAScript并未认可（见 `ECMA-262 <https://www.ecma-international.org/publications/standards/Ecma-262.htm>`_ ，第13条和第14）。若与他人的及EcmaScript所建议的不一致，即可视为不好的实现方式。ECMAScript只允许函数声明语句列表, 在根语句列表脚本或者函数。相反，使用一个变量初始化函数表达式在块内定义一个函数块：
|
||||
|
||||
::
|
||||
|
||||
@ -279,7 +279,7 @@ js语句要求以分号结尾，除非能够正确地推断分号的位置。在
|
||||
|
||||
可以使用，但是要小心。
|
||||
|
||||
创建闭包可能是JS最有用的和经常被忽视的功能。在 `这里 <http://jibbering.com/faq/notes/closures/>`_ 很好地描述说明了闭包的工作。
|
||||
创建闭包可能是JS最有用的和经常被忽视的功能。在 `这里 <https://jibbering.com/faq/notes/closures/>`_ 很好地描述说明了闭包的工作。
|
||||
|
||||
要记住的一件事情，一个闭包的指针指向包含它的范围。因此，附加一个闭包的DOM元素，可以创建一个循环引用，所以，内存会泄漏。例如，下面的代码：
|
||||
|
||||
@ -336,7 +336,7 @@ eval()函数
|
||||
var userOnline = false;
|
||||
var user = 'nusrat';
|
||||
var xmlhttp = new XMLHttpRequest();
|
||||
xmlhttp.open('GET', 'http://chat.google.com/isUserOnline?user=' + user, false);
|
||||
xmlhttp.open('GET', 'https://chat.google.com/isUserOnline?user=' + user, false);
|
||||
xmlhttp.send('');
|
||||
// 服务器返回：
|
||||
// userOnline = true;
|
||||
|
||||
@ -13,7 +13,7 @@ Javascript风格规范
|
||||
|
||||
* *保护* 属性和方法应该以无下划线开头命名（像公共属性和方法一样）。
|
||||
|
||||
了解更多关于私有成员和保护成员的信息，请阅读 `可见性 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Visibility__private_and_protected_fields_>`_ 部分。
|
||||
了解更多关于私有成员和保护成员的信息，请阅读 `可见性 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Visibility__private_and_protected_fields_>`_ 部分。
|
||||
|
||||
方法和函数参数
|
||||
~~~~~~~~~~~~~~~~~
|
||||
@ -62,7 +62,7 @@ JavaScript没有原生的对封装和命名空间的支持。
|
||||
...
|
||||
};
|
||||
|
||||
很多JavaScript库，包括 `the Closure Library <https://developers.google.com/closure/library/?csw=1>`_ 和 `Dojo toolkit <http://dojotoolkit.org/>`_ 给你高级功能来声明命名空间。保持你的命名空间声明一致。
|
||||
很多JavaScript库，包括 `the Closure Library <https://developers.google.com/closure/library/?csw=1>`_ 和 `Dojo toolkit <https://dojotoolkit.org/>`_ 给你高级功能来声明命名空间。保持你的命名空间声明一致。
|
||||
|
||||
::
|
||||
|
||||
@ -135,7 +135,7 @@ JavaScript没有原生的对封装和命名空间的支持。
|
||||
staticHelper(new MyClass());
|
||||
};
|
||||
|
||||
不要为命名空间起本地别名。命名空间应该只能使用 `goog.scope <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#goog-scope>`_ 命名别名。
|
||||
不要为命名空间起本地别名。命名空间应该只能使用 `goog.scope <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#goog-scope>`_ 命名别名。
|
||||
|
||||
::
|
||||
|
||||
@ -202,7 +202,7 @@ JavaScript没有原生的对封装和命名空间的支持。
|
||||
代码格式
|
||||
----------
|
||||
|
||||
我们原则上遵循 `C++格式规范 <http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Formatting>`_ ，并且进行以下额外的说明。
|
||||
我们原则上遵循 `C++格式规范 <https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Formatting>`_ ，并且进行以下额外的说明。
|
||||
|
||||
大括号
|
||||
~~~~~~~~
|
||||
@ -400,7 +400,7 @@ JavaScript没有原生的对封装和命名空间的支持。
|
||||
更多的缩进
|
||||
~~~~~~~~~~~~
|
||||
|
||||
事实上，除了 `初始化数组和对象 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Array_and_Object_literals>`_ 和传递匿名函数外，所有被拆开的多行文本应与之前的表达式左对齐，或者以4个（而不是2个）空格作为一缩进层次。
|
||||
事实上，除了 `初始化数组和对象 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Array_and_Object_literals>`_ 和传递匿名函数外，所有被拆开的多行文本应与之前的表达式左对齐，或者以4个（而不是2个）空格作为一缩进层次。
|
||||
|
||||
::
|
||||
|
||||
@ -591,7 +591,7 @@ JavaScript类型
|
||||
|
||||
鼓励和强制执行的编译器。
|
||||
|
||||
JSDoc记录类型时，要尽可能具体和准确。我们支持的类型是基于 `EcmaScript 4规范 <http://wiki.ecmascript.org/doku.php?id=spec:spec>`_ 。
|
||||
JSDoc记录类型时，要尽可能具体和准确。我们支持的类型是基于 `EcmaScript 4规范 <https://wiki.ecmascript.org/doku.php?id=spec:spec>`_ 。
|
||||
|
||||
JavaScript类型语言
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
@ -627,7 +627,7 @@ ES4提案包含指定JavaScript类型的语言。我们使用JsDoc这种语言
|
||||
-
|
||||
* - 枚举类型
|
||||
- ``{goog.events.EventType}`` 字面量初始化对象的属性之一 ``goog.events.EventType`` 。
|
||||
- 一个枚举必须被初始化为一个字面量对象，或作为另一个枚举的别名,加注 ``@enum`` JSDoc标记。这个属性是枚举实例。 `下面 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#enums>`_ 是枚举语法的定义。
|
||||
- 一个枚举必须被初始化为一个字面量对象，或作为另一个枚举的别名,加注 ``@enum`` JSDoc标记。这个属性是枚举实例。 `下面 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#enums>`_ 是枚举语法的定义。
|
||||
|
||||
请注意，这是我们的类型系统中为数不多的ES4规范以外的事情之一。
|
||||
-
|
||||
@ -704,13 +704,13 @@ ES4提案包含指定JavaScript类型的语言。我们使用JsDoc这种语言
|
||||
带注释函数的可变数目参数。
|
||||
- 指定带注释函数接受一个可变数目的参数。
|
||||
-
|
||||
* - 函数 `可选参数 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#optional>`_
|
||||
* - 函数 `可选参数 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#optional>`_
|
||||
- ``{function(?string=, number=)}``
|
||||
|
||||
一个函数，它接受一个可选的、可以为空的字符串和一个可选的数字作为参数。“=”只用于函数类型声明。
|
||||
- 指定函数的可选参数。
|
||||
-
|
||||
* - 函数 `可选参数 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#optional>`_ （ ``@param`` 注释）
|
||||
* - 函数 `可选参数 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#optional>`_ （ ``@param`` 注释）
|
||||
- ``@param {number=} opt_argument``
|
||||
|
||||
``number`` 类型的可选参数。
|
||||
@ -748,7 +748,7 @@ JavaScript中的类型
|
||||
- ::
|
||||
|
||||
new Number(true)
|
||||
- `Number对象 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Wrapper_objects_for_primitive_types>`_
|
||||
- `Number对象 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Wrapper_objects_for_primitive_types>`_
|
||||
* - string
|
||||
- ::
|
||||
|
||||
@ -761,7 +761,7 @@ JavaScript中的类型
|
||||
|
||||
new String('Hello')
|
||||
new String(42)
|
||||
- `String对象 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Wrapper_objects_for_primitive_types>`_
|
||||
- `String对象 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Wrapper_objects_for_primitive_types>`_
|
||||
* - boolean
|
||||
- ::
|
||||
|
||||
@ -773,7 +773,7 @@ JavaScript中的类型
|
||||
- ::
|
||||
|
||||
new Boolean(true)
|
||||
- `Boolean对象 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Wrapper_objects_for_primitive_types>`_
|
||||
- `Boolean对象 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Wrapper_objects_for_primitive_types>`_
|
||||
* - RegExp
|
||||
- ::
|
||||
|
||||
@ -843,7 +843,7 @@ JavaScript中的类型
|
||||
function(x, y) {
|
||||
return x * y;
|
||||
}
|
||||
- `Function对象 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Wrapper_objects_for_primitive_types>`_
|
||||
- `Function对象 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Wrapper_objects_for_primitive_types>`_
|
||||
* - function(number, number): number
|
||||
- ::
|
||||
|
||||
@ -1053,8 +1053,8 @@ JavaScript中的类型
|
||||
|
||||
使用JSDoc。
|
||||
|
||||
我们使用 `c++的注释风格 <http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Comments>`_ 。
|
||||
所有的文件、类、方法和属性都应该用合适的 `JSDoc <https://code.google.com/p/jsdoc-toolkit/>`_ 的 `标签 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JSDoc_Tag_Reference>`_ 和 `类型 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JsTypes>`_ 注释。除了直观的方法名称和参数名称外，方法的描述、方法的参数以及方法的返回值也要包含进去。
|
||||
我们使用 `c++的注释风格 <https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Comments>`_ 。
|
||||
所有的文件、类、方法和属性都应该用合适的 `JSDoc <https://code.google.com/p/jsdoc-toolkit/>`_ 的 `标签 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JSDoc_Tag_Reference>`_ 和 `类型 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JsTypes>`_ 注释。除了直观的方法名称和参数名称外，方法的描述、方法的参数以及方法的返回值也要包含进去。
|
||||
|
||||
行内注释应该使用 ``//`` 的形式。
|
||||
|
||||
@ -1063,7 +1063,7 @@ JavaScript中的类型
|
||||
注释语法
|
||||
~~~~~~~~~~
|
||||
|
||||
JSDoc的语法基于 `JavaDoc <http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html>`_ ，许多编译工具从JSDoc注释中获取信息从而进行代码验证和优化，所以这些注释必须符合语法规则。
|
||||
JSDoc的语法基于 `JavaDoc <https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html>`_ ，许多编译工具从JSDoc注释中获取信息从而进行代码验证和优化，所以这些注释必须符合语法规则。
|
||||
|
||||
::
|
||||
|
||||
@ -1143,12 +1143,12 @@ JSDoc中的HTML
|
||||
* </ul>
|
||||
*/
|
||||
|
||||
`JavaDoc <http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html>`_ 风格指南对于如何编写良好的doc注释是非常有帮助的。
|
||||
`JavaDoc <https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html>`_ 风格指南对于如何编写良好的doc注释是非常有帮助的。
|
||||
|
||||
顶层/文件层注释
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`版权声明 <http://google-styleguide.googlecode.com/svn/trunk/copyright.html>`_ 和作者信息是可选的。顶层注释的目的是为了让不熟悉代码的读者了解文件中有什么。它需要描述文件内容，依赖关系以及兼容性的信息。例如：
|
||||
`版权声明 <https://google-styleguide.googlecode.com/svn/trunk/copyright.html>`_ 和作者信息是可选的。顶层注释的目的是为了让不熟悉代码的读者了解文件中有什么。它需要描述文件内容，依赖关系以及兼容性的信息。例如：
|
||||
|
||||
::
|
||||
|
||||
@ -1160,7 +1160,7 @@ JSDoc中的HTML
|
||||
Class评论
|
||||
~~~~~~~~~~~
|
||||
|
||||
类必须记录说明与描述和 `一个类型的标签 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#constructor-tag>`_ ，标识的构造函数。类必须加以描述，若是构造函数则需标注出。
|
||||
类必须记录说明与描述和 `一个类型的标签 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#constructor-tag>`_ ，标识的构造函数。类必须加以描述，若是构造函数则需标注出。
|
||||
|
||||
::
|
||||
|
||||
@ -1278,7 +1278,7 @@ JSDoc标签参考
|
||||
|
||||
当一个方法被标记为 ``@const`` ，意味着这个方法不仅不可以被覆盖，而且也不能在子类中重写。
|
||||
|
||||
``@const`` 的更多信息，请看 `常量 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Constants>`_ 部分
|
||||
``@const`` 的更多信息，请看 `常量 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Constants>`_ 部分
|
||||
* - @constructor
|
||||
- @constructor
|
||||
|
||||
@ -1603,7 +1603,7 @@ JSDoc标签参考
|
||||
};
|
||||
- 给方法、函数、构造函数的参数添加文档说明。
|
||||
|
||||
`参数类型 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JsTypes>`_ 一定要写在大括号里。如果类型被省略，编译器将不做类型检测。
|
||||
`参数类型 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JsTypes>`_ 一定要写在大括号里。如果类型被省略，编译器将不做类型检测。
|
||||
* - @private
|
||||
- @private
|
||||
@private {type}
|
||||
@ -1617,7 +1617,7 @@ JSDoc标签参考
|
||||
* @private {!Array.<Function>}
|
||||
*/
|
||||
this.handlers\_ = [];
|
||||
- 与方法或属性名结尾使用一个下划线来联合表明该成员是 `私有的 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Visibility__private_and_protected_fields_>`_ 。随着工具对 ``@private`` 的认可，结尾的下划线可能最终被废弃。
|
||||
- 与方法或属性名结尾使用一个下划线来联合表明该成员是 `私有的 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Visibility__private_and_protected_fields_>`_ 。随着工具对 ``@private`` 的认可，结尾的下划线可能最终被废弃。
|
||||
* - @protected
|
||||
- @protected
|
||||
@protected {type}
|
||||
@ -1635,7 +1635,7 @@ JSDoc标签参考
|
||||
goog.ui.Component.prototype.setElementInternal = function(element) {
|
||||
// ...
|
||||
};
|
||||
- 用来表明成员或属性是 ``受保护的 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Visibility__private_and_protected_fields_>``_ 。成员或属性应使用没有跟随下划线的名称。
|
||||
- 用来表明成员或属性是 ``受保护的 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Visibility__private_and_protected_fields_>``_ 。成员或属性应使用没有跟随下划线的名称。
|
||||
* - @return
|
||||
- @return {Type} Description
|
||||
|
||||
@ -1652,7 +1652,7 @@ JSDoc标签参考
|
||||
};
|
||||
- 在方法或函数调用时使用，来说明返回类型。给布尔值写注释时，写成类似“这个组件是否可见”比“如果组件可见则为true，否则为false”要好。如果没有返回值，不使用 ``@return`` 标签。
|
||||
|
||||
`类型 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JsTypes>`_ 名称必须包含在大括号内。如果省略类型，编译器将不会检查返回值的类型。
|
||||
`类型 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JsTypes>`_ 名称必须包含在大括号内。如果省略类型，编译器将不会检查返回值的类型。
|
||||
* - @see
|
||||
- @see Link
|
||||
|
||||
@ -1734,7 +1734,7 @@ JSDoc标签参考
|
||||
goog.bind = function(fn, thisObj, var_args) {
|
||||
...
|
||||
};
|
||||
- 这个注释可以用来声明一个 `模板类型名 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Template_types>`_ 。
|
||||
- 这个注释可以用来声明一个 `模板类型名 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Template_types>`_ 。
|
||||
* - @this
|
||||
- @this Type
|
||||
@this {Type}
|
||||
@ -1766,7 +1766,7 @@ JSDoc标签参考
|
||||
* @type {string}
|
||||
*/
|
||||
var hexId = hexId;
|
||||
- 标识变量，属性或表达式的 `类型 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JsTypes>`_ 。大多数类型不需要大括号，但有些项目为了保持一致性而要求所有类型都使用大括号。
|
||||
- 标识变量，属性或表达式的 `类型 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JsTypes>`_ 。大多数类型不需要大括号，但有些项目为了保持一致性而要求所有类型都使用大括号。
|
||||
* - @typedef
|
||||
- @typedef
|
||||
|
||||
@ -1780,7 +1780,7 @@ JSDoc标签参考
|
||||
goog.readNumber = function(x) {
|
||||
...
|
||||
}
|
||||
- 使用此注释来声明一个更 `复杂的类型 <http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Typedefs>`_ 的别名。
|
||||
- 使用此注释来声明一个更 `复杂的类型 <https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Typedefs>`_ 的别名。
|
||||
|
||||
你也许在第三方代码中看到其他类型JSDoc注释，这些注释出现在 `JSDoc Toolkit标签的参考 <https://code.google.com/p/jsdoc-toolkit/wiki/TagReference>`_ ，但目前在谷歌的代码中不鼓励使用。你应该将他们当作“保留”字，他们包括：
|
||||
|
||||
|
||||
@ -80,7 +80,7 @@
|
||||
|
||||
当实例变量指向 ``CoreFoundation``、C++ 或者其它非 Objective-C 对象时，不论指针是否会被 ``retained``，都需要使用 ``__strong`` 和 ``__weak`` 类型修饰符明确指明。``CoreFoundation`` 和其它非 Objective-C 对象指针需要显式的内存管理，即便使用了自动引用计数或垃圾回收机制。当不允许使用 ``__weak`` 类型修饰符（比如，使用 clang 编译时的 C++ 成员变量），应使用注释替代说明。
|
||||
|
||||
注意：Objective-C 对象中的 C++ 对象的自动封装，缺省是不允许的，参见 `这里 <http://chanson.livejournal.com/154253.html>`_ 的说明。
|
||||
注意：Objective-C 对象中的 C++ 对象的自动封装，缺省是不允许的，参见 `这里 <https://chanson.livejournal.com/154253.html>`_ 的说明。
|
||||
|
||||
强引用及弱引用声明的例子：
|
||||
|
||||
|
||||
@ -99,7 +99,7 @@ Cocoa 和 Objective-C 特性
|
||||
|
||||
Objective-C 2.0 以前，如果你在私有的 ``@interface`` 中声明了某个方法，但在 ``@implementation`` 中忘记定义这个方法，编译器不会抱怨（这是因为你没有在其它的类别中实现这个私有的方法）。解决文案是将方法放进指定类别的 ``@implemenation`` 中。
|
||||
|
||||
如果你在使用 Objective-C 2.0，相反你应该使用 `类扩展 <http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_4_section_5.html>`_ 来声明你的私有类别，例如：
|
||||
如果你在使用 Objective-C 2.0，相反你应该使用 `类扩展 <https://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_4_section_5.html>`_ 来声明你的私有类别，例如：
|
||||
|
||||
.. code-block:: objc
|
||||
|
||||
@ -121,7 +121,7 @@ Objective-C 的类别可以用来将一个大的 ``@implementation`` 拆分成
|
||||
基于你所包括的头文件的编程语言，选择使用 ``#import`` 或是 ``#include``：
|
||||
|
||||
* 当包含一个使用 Objective-C、Objective-C++ 的头文件时，使用 ``#import`` 。
|
||||
* 当包含一个使用标准 C、C++ 头文件时，使用 ``#include``。头文件应该使用 `#define 保护 <http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=The__define_Guard#The__define_Guard>`_。
|
||||
* 当包含一个使用标准 C、C++ 头文件时，使用 ``#include``。头文件应该使用 `#define 保护 <https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=The__define_Guard#The__define_Guard>`_。
|
||||
|
||||
一些 Objective-C 的头文件缺少 ``#define`` 保护，需要使用 ``#import`` 的方式包含。由于 Objective-C 的头文件只会被 Objective-C 的源文件及头文件包含，广泛地使用 ``#import`` 是可以的。
|
||||
|
||||
@ -326,7 +326,7 @@ nil 检查
|
||||
|
||||
|
||||
|
||||
使用 ``nil`` 的检查来检查应用程序的逻辑流程，而不是避免崩溃。Objective-C 运行时会处理向 ``nil`` 对象发送消息的情况。如果方法没有返回值，就没关系。如果有返回值，可能由于运行时架构、返回值类型以及 OS X 版本的不同而不同，参见 `Apple’s documentation <http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_2_section_3.html>`_ 。
|
||||
使用 ``nil`` 的检查来检查应用程序的逻辑流程，而不是避免崩溃。Objective-C 运行时会处理向 ``nil`` 对象发送消息的情况。如果方法没有返回值，就没关系。如果有返回值，可能由于运行时架构、返回值类型以及 OS X 版本的不同而不同，参见 `Apple’s documentation <https://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_2_section_3.html>`_ 。
|
||||
|
||||
注意，这和 C/C++ 中检查指针是否为 ‵‵NULL`` 很不一样，C/C++ 运行时不做任何检查，从而导致应用程序崩溃。因此你仍然需要保证你不会对一个 C/C++ 的空指针解引用。
|
||||
|
||||
|
||||
@ -14,12 +14,12 @@ Google Objective-C Style Guide 中文版
|
||||
:翻译:
|
||||
.. line-block::
|
||||
|
||||
`ewangke <http://ke.indiebros.com/>`_
|
||||
`ewangke <https://ke.indiebros.com/>`_
|
||||
`Yang.Y <https://github.com/yangyubo>`_
|
||||
|
||||
:项目主页:
|
||||
- `Google Style Guide <http://google-styleguide.googlecode.com>`_
|
||||
- `Google 开源项目风格指南 - 中文版 <http://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
- `Google Style Guide <https://google-styleguide.googlecode.com>`_
|
||||
- `Google 开源项目风格指南 - 中文版 <https://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
|
||||
|
||||
译者的话
|
||||
@ -28,7 +28,7 @@ Google Objective-C Style Guide 中文版
|
||||
ewanke
|
||||
^^^^^^^^^^^^
|
||||
|
||||
一直想翻译这个 `style guide <http://google-styleguide.googlecode.com/svn/trunk/objcguide.xml>`_ ，终于在周末花了7个小时的时间用vim敲出了HTML。很多术语的翻译很难，平时看的中文技术类书籍有限，对很多术语的中文译法不是很清楚，难免有不恰当之处，请读者指出并帮我改进：王轲 ”ewangke at gmail.com” 2011.03.27
|
||||
一直想翻译这个 `style guide <https://google-styleguide.googlecode.com/svn/trunk/objcguide.xml>`_ ，终于在周末花了7个小时的时间用vim敲出了HTML。很多术语的翻译很难，平时看的中文技术类书籍有限，对很多术语的中文译法不是很清楚，难免有不恰当之处，请读者指出并帮我改进：王轲 ”ewangke at gmail.com” 2011.03.27
|
||||
|
||||
Yang.Y
|
||||
^^^^^^^^^^^^
|
||||
@ -48,9 +48,9 @@ Cocoa 是 Mac OS X 上主要的应用程序框架之一。它由一组 Objective
|
||||
|
||||
苹果公司已经有一份非常全面的 Objective-C 编码指南。Google 为 C++ 也写了一份类似的编码指南。而这份 Objective-C 指南则是苹果和 Google 常规建议的最佳结合。因此，在阅读本指南之前，请确定你已经阅读过：
|
||||
|
||||
* `Apple’s Cocoa Coding Guidelines <http://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/index.html>`_
|
||||
* `Apple’s Cocoa Coding Guidelines <https://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/index.html>`_
|
||||
|
||||
* `Google’s Open Source C++ Style Guide <http://codinn.com/projects/google-cpp-styleguide/>`_
|
||||
* `Google’s Open Source C++ Style Guide <https://codinn.com/projects/google-cpp-styleguide/>`_
|
||||
|
||||
.. note::
|
||||
|
||||
@ -58,9 +58,9 @@ Cocoa 是 Mac OS X 上主要的应用程序框架之一。它由一组 Objective
|
||||
|
||||
本文档的目的在于为所有的 Mac OS X 的代码提供编码指南及实践。许多准则是在实际的项目和小组中经过长期的演化、验证的。Google 开发的开源项目遵从本指南的要求。
|
||||
|
||||
Google 已经发布了遵守本指南开源代码，它们属于 `Google Toolbox for Mac project <http://code.google.com/p/google-toolbox-for-mac/>`_ 项目（本文以缩写 GTM 指代）。GTM 代码库中的代码通常为了可以在不同项目中复用。
|
||||
Google 已经发布了遵守本指南开源代码，它们属于 `Google Toolbox for Mac project <https://code.google.com/p/google-toolbox-for-mac/>`_ 项目（本文以缩写 GTM 指代）。GTM 代码库中的代码通常为了可以在不同项目中复用。
|
||||
|
||||
注意，本指南不是 Objective-C 教程。我们假定读者对 Objective-C 非常熟悉。如果你刚刚接触 Objective-C 或者需要温习，请阅读 `The Objective-C Programming Language <http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html>`_ 。
|
||||
注意，本指南不是 Objective-C 教程。我们假定读者对 Objective-C 非常熟悉。如果你刚刚接触 Objective-C 或者需要温习，请阅读 `The Objective-C Programming Language <https://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html>`_ 。
|
||||
|
||||
例子
|
||||
========
|
||||
|
||||
@ -4,9 +4,9 @@
|
||||
|
||||
对于易维护的代码而言，命名规则非常重要。Objective-C 的方法名往往十分长，但代码块读起来就像散文一样，不需要太多的代码注释。
|
||||
|
||||
当编写纯粹的 Objective-C 代码时，我们基本遵守标准的 `Objective-C naming rules <http://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html>`_，这些命名规则可能与 C++ 风格指南中的大相径庭。例如，Google 的 C++ 风格指南中推荐使用下划线分隔的单词作为变量名，而(苹果的)风格指南则使用驼峰命名法，这在 Objective-C 社区中非常普遍。
|
||||
当编写纯粹的 Objective-C 代码时，我们基本遵守标准的 `Objective-C naming rules <https://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html>`_，这些命名规则可能与 C++ 风格指南中的大相径庭。例如，Google 的 C++ 风格指南中推荐使用下划线分隔的单词作为变量名，而(苹果的)风格指南则使用驼峰命名法，这在 Objective-C 社区中非常普遍。
|
||||
|
||||
任何的类、类别、方法以及变量的名字中都使用全大写的 `首字母缩写 <http://en.wikipedia.org/wiki/Initialism>`_。这遵守了苹果的标准命名方式，如 URL、TIFF 以及 EXIF。
|
||||
任何的类、类别、方法以及变量的名字中都使用全大写的 `首字母缩写 <https://en.wikipedia.org/wiki/Initialism>`_。这遵守了苹果的标准命名方式，如 URL、TIFF 以及 EXIF。
|
||||
|
||||
当编写 Objective-C++ 代码时，事情就不这么简单了。许多项目需要实现跨平台的 C++ API，并混合一些 Objective-C、Cocoa 代码，或者直接以 C++ 为后端，前端用本地 Cocoa 代码。这就导致了两种命名方式直接不统一。
|
||||
|
||||
@ -111,7 +111,7 @@ Objective-C 方法名
|
||||
|
||||
方法名应该以小写字母开头，并混合驼峰格式。每个具名参数也应该以小写字母开头。
|
||||
|
||||
方法名应尽量读起来就像句子，这表示你应该选择与方法名连在一起读起来通顺的参数名。（例如，``convertPoint:fromRect:`` 或 ``replaceCharactersInRange:withString:``）。详情参见 `Apple’s Guide to Naming Methods <http://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html>`_。
|
||||
方法名应尽量读起来就像句子，这表示你应该选择与方法名连在一起读起来通顺的参数名。（例如，``convertPoint:fromRect:`` 或 ``replaceCharactersInRange:withString:``）。详情参见 `Apple’s Guide to Naming Methods <https://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html>`_。
|
||||
|
||||
访问器方法应该与他们 ``要获取的`` 成员变量的名字一样，但不应该以get作为前缀。例如：
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
https://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
@ -193,7 +193,7 @@
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
https://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
|
||||
@ -16,14 +16,14 @@
|
||||
:翻译:
|
||||
.. line-block::
|
||||
|
||||
`guoqiao <http://guoqiao.me/>`_ v2.19
|
||||
`guoqiao <https://guoqiao.me/>`_ v2.19
|
||||
`xuxinkun <https://github.com/xuxinkun>`_ v2.59
|
||||
`captainfffsama <https://github.com/captainfffsama>`_ v2.6
|
||||
`楼宇 <https://github.com/LouYu2015>`_ 2023 年 4 月 16 日更新
|
||||
|
||||
:项目主页:
|
||||
- `Google Style Guide (英文原版) <https://github.com/google/styleguide>`_
|
||||
- `Google 开源项目风格指南 - 中文版 <http://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
- `Google 开源项目风格指南 - 中文版 <https://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
|
||||
:协议:
|
||||
Python风格指南的源文件采用Apache License 2.0协议, 文本内容采用 `CC-BY 3.0 <https://creativecommons.org/licenses/by/3.0/>`_ 协议.
|
||||
|
||||
@ -524,7 +524,7 @@ Lambda函数
|
||||
|
||||
举个例子, 一个特性不能仅仅用于获取和设置一个内部属性: 因为不涉及计算, 没有必要用特性 (应该把该属性设为公有). 而用特性来限制属性的访问或者计算 **简单** 的衍生值则是正确的: 这种逻辑简单明了.
|
||||
|
||||
应该用 ``@property`` `装饰器 (decorator) <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Function_and_Method_Decorators>`_ 来创建特性. 自行实现的特性装饰器属于威力过大的功能.
|
||||
应该用 ``@property`` `装饰器 (decorator) <https://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Function_and_Method_Decorators>`_ 来创建特性. 自行实现的特性装饰器属于威力过大的功能.
|
||||
|
||||
特性的继承机制难以理解. 不要用特性实现子类能覆写 (override) 或扩展的计算功能.
|
||||
|
||||
@ -607,7 +607,7 @@ True/False的求值
|
||||
通常会产生更清晰、更优雅的代码. 尤其是让熟练使用Lisp和Scheme(还有Haskell, ML等)的程序员感到舒适.
|
||||
|
||||
缺点:
|
||||
可能引发让人困惑的bug, 例如下面这个依据 `PEP-0227 <http://www.python.org/dev/peps/pep-0227/>`_ 改编的例子:
|
||||
可能引发让人困惑的bug, 例如下面这个依据 `PEP-0227 <https://www.python.org/dev/peps/pep-0227/>`_ 改编的例子:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
@ -24,7 +24,7 @@ Python风格规范
|
||||
|
||||
不要用反斜杠表示 `显式续行 (explicit line continuation) <https://docs.python.org/3/reference/lexical_analysis.html#explicit-line-joining>`_.
|
||||
|
||||
应该利用 Python 的 `圆括号, 中括号和花括号的隐式续行 (implicit line joining) <http://docs.python.org/2/reference/lexical_analysis.html#implicit-line-joining>`_ . 如有需要, 你可以在表达式外围添加一对括号.
|
||||
应该利用 Python 的 `圆括号, 中括号和花括号的隐式续行 (implicit line joining) <https://docs.python.org/2/reference/lexical_analysis.html#implicit-line-joining>`_ . 如有需要, 你可以在表达式外围添加一对括号.
|
||||
|
||||
正确:
|
||||
|
||||
@ -108,14 +108,14 @@ Python风格规范
|
||||
.. code-block:: python
|
||||
|
||||
# 详情参见
|
||||
# http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html
|
||||
# https://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html
|
||||
|
||||
错误:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# 详情参见
|
||||
# http://www.example.com/us/developer/documentation/api/content/\
|
||||
# https://www.example.com/us/developer/documentation/api/content/\
|
||||
# v2.0/csv_file_name_extension_full_specification.html
|
||||
|
||||
注意上面各个例子中的缩进; 详情参见 :ref:`缩进 <indentation>` 章节的解释.
|
||||
@ -242,9 +242,9 @@ Shebang行
|
||||
--------------------
|
||||
|
||||
.. tip::
|
||||
大部分 ``.py`` 文件不必以 ``#!`` 开始. 可以根据 `PEP-394 <http://www.python.org/dev/peps/pep-0394/>`_ , 在程序的主文件开头添加 ``#!/usr/bin/env python3`` (以支持 virtualenv) 或者 ``#!/usr/bin/python3``.
|
||||
大部分 ``.py`` 文件不必以 ``#!`` 开始. 可以根据 `PEP-394 <https://www.python.org/dev/peps/pep-0394/>`_ , 在程序的主文件开头添加 ``#!/usr/bin/env python3`` (以支持 virtualenv) 或者 ``#!/usr/bin/python3``.
|
||||
|
||||
(译者注: 在计算机科学中, `Shebang <http://en.wikipedia.org/wiki/Shebang_(Unix)>`_ (也称为Hashbang)是一个由井号和叹号构成的字符串行(#!), 其出现在文本文件的第一行的前两个字符. 在文件中存在Shebang的情况下, 类Unix操作系统的程序载入器会分析Shebang后的内容, 将这些内容作为解释器指令, 并调用该指令, 并将载有Shebang的文件路径作为该解释器的参数. 例如, 以指令#!/bin/sh开头的文件在执行时会实际调用/bin/sh程序.)
|
||||
(译者注: 在计算机科学中, `Shebang <https://en.wikipedia.org/wiki/Shebang_(Unix)>`_ (也称为Hashbang)是一个由井号和叹号构成的字符串行(#!), 其出现在文本文件的第一行的前两个字符. 在文件中存在Shebang的情况下, 类Unix操作系统的程序载入器会分析Shebang后的内容, 将这些内容作为解释器指令, 并调用该指令, 并将载有Shebang的文件路径作为该解释器的参数. 例如, 以指令#!/bin/sh开头的文件在执行时会实际调用/bin/sh程序.)
|
||||
|
||||
内核会通过这行内容找到Python解释器, 但是Python解释器在导入模块时会忽略这行内容. 这行内容仅对需要直接运行的文件有效.
|
||||
|
||||
@ -258,7 +258,7 @@ Shebang行
|
||||
|
||||
**文档字符串**
|
||||
|
||||
Python 的文档字符串用于注释代码. 文档字符串是包、模块、类或函数里作为第一个语句的字符串. 可以用对象的 ``__doc__`` 成员自动提取这些字符串, 并为 ``pydoc`` 所用. (可以试试在你的模块上运行 ``pydoc`` 并观察结果). 文档字符串一定要用三重双引号 ``"""`` 的格式 (依据 `PEP-257 <http://www.python.org/dev/peps/pep-0257/>`_ ). 文档字符串应该是一行概述 (整行不超过 80 个字符), 以句号、问号或感叹号结尾. 如果要写更多注释 (推荐), 那么概述后面必须紧接着一个空行, 然后是剩下的内容, 缩进与文档字符串的第一行第一个引号对齐. 下面是更多有关文档字符串的格式规范.
|
||||
Python 的文档字符串用于注释代码. 文档字符串是包、模块、类或函数里作为第一个语句的字符串. 可以用对象的 ``__doc__`` 成员自动提取这些字符串, 并为 ``pydoc`` 所用. (可以试试在你的模块上运行 ``pydoc`` 并观察结果). 文档字符串一定要用三重双引号 ``"""`` 的格式 (依据 `PEP-257 <https://www.python.org/dev/peps/pep-0257/>`_ ). 文档字符串应该是一行概述 (整行不超过 80 个字符), 以句号、问号或感叹号结尾. 如果要写更多注释 (推荐), 那么概述后面必须紧接着一个空行, 然后是剩下的内容, 缩进与文档字符串的第一行第一个引号对齐. 下面是更多有关文档字符串的格式规范.
|
||||
|
||||
**模块**
|
||||
|
||||
@ -325,7 +325,7 @@ Shebang行
|
||||
Returns: ("返回:")
|
||||
生成器应该用 "Yields:" ("生成:" )
|
||||
|
||||
描述返回值的类型和意义. 如果函数仅仅返回 ``None``, 这一小节可以省略. 如果文档字符串以 Returns (返回) 或者 Yields (生成) 开头 (例如 ``"""返回 Bigtable 的行, 类型是字符串构成的元组."""``) 且这句话已经足以描述返回值, 也可以省略这一小节. 不要模仿 Numpy 风格的文档 (`例子 <http://numpy.org/doc/stable/reference/generated/numpy.linalg.qr.html>`_). 他们在文档中记录作为返回值的元组时, 写得就像返回值是多个值且每个值都有名字 (没有提到返回的是元组). 应该这样描述此类情况: "返回: 一个元组 (mat_a, mat_b), 其中 mat_a 是..., 且 ...". 文档字符串中使用的辅助名称不需要和函数体的内部变量名一致 (因为这些名称不是 API 的一部分).
|
||||
描述返回值的类型和意义. 如果函数仅仅返回 ``None``, 这一小节可以省略. 如果文档字符串以 Returns (返回) 或者 Yields (生成) 开头 (例如 ``"""返回 Bigtable 的行, 类型是字符串构成的元组."""``) 且这句话已经足以描述返回值, 也可以省略这一小节. 不要模仿 Numpy 风格的文档 (`例子 <https://numpy.org/doc/stable/reference/generated/numpy.linalg.qr.html>`_). 他们在文档中记录作为返回值的元组时, 写得就像返回值是多个值且每个值都有名字 (没有提到返回的是元组). 应该这样描述此类情况: "返回: 一个元组 (mat_a, mat_b), 其中 mat_a 是..., 且 ...". 文档字符串中使用的辅助名称不需要和函数体的内部变量名一致 (因为这些名称不是 API 的一部分).
|
||||
|
||||
Raises: (抛出:)
|
||||
列出与接口相关的所有异常和异常描述. 用类似 Args (参数) 小节的格式，写成异常名+冒号+空格/换行, 并添加悬挂缩进. 不要在文档中记录违反 API 的使用条件时会抛出的异常 (因为这会让违背 API 时出现的效果成为 API 的一部分, 这是矛盾的).
|
||||
@ -453,7 +453,7 @@ Shebang行
|
||||
|
||||
**块注释和行注释**
|
||||
|
||||
最后一种需要写注释的地方是代码中复杂的部分. 如果你可能在以后 `代码评审 (code review) <http://en.wikipedia.org/wiki/Code_review>`_ 时要解释某段代码, 那么现在就应该给这段代码加上注释. 应该在复杂的操作开始前写上若干行注释. 对于不是一目了然的代码, 应该在行尾添加注释.
|
||||
最后一种需要写注释的地方是代码中复杂的部分. 如果你可能在以后 `代码评审 (code review) <https://en.wikipedia.org/wiki/Code_review>`_ 时要解释某段代码, 那么现在就应该给这段代码加上注释. 应该在复杂的操作开始前写上若干行注释. 对于不是一目了然的代码, 应该在行尾添加注释.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -694,7 +694,7 @@ Shebang行
|
||||
|
||||
import contextlib
|
||||
|
||||
with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
|
||||
with contextlib.closing(urllib.urlopen("https://www.python.org/")) as front_page:
|
||||
for line in front_page:
|
||||
print line
|
||||
|
||||
|
||||
@ -33,7 +33,7 @@ test，[和[[
|
||||
# alnum character class followed by the string name.
|
||||
# Note that the RHS should not be quoted here.
|
||||
# For the gory details, see
|
||||
# E14 at http://tiswww.case.edu/php/chet/bash/FAQ
|
||||
# E14 at https://tiswww.case.edu/php/chet/bash/FAQ
|
||||
if [[ "filename" =~ ^[[:alnum:]]+name ]]; then
|
||||
echo "Match"
|
||||
fi
|
||||
|
||||
@ -14,10 +14,10 @@
|
||||
|
||||
.. line-block::
|
||||
|
||||
`Bean Zhang <http://87boy.me/>`_ v1.26
|
||||
`Bean Zhang <https://87boy.me/>`_ v1.26
|
||||
|
||||
:项目主页:
|
||||
|
||||
- `Google Style Guide <https://github.com/google/styleguide>`_
|
||||
- `Google 开源项目风格指南 - 中文版 <http://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
- `Google 开源项目风格指南 - 中文版 <https://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
|
||||
|
||||
16
google-typescript-styleguide/index.rst
Normal file
16
google-typescript-styleguide/index.rst
Normal file
@ -0,0 +1,16 @@
|
||||
0. 扉页
|
||||
============
|
||||
|
||||
:原作者:
|
||||
.. line-block::
|
||||
|
||||
详细作者列表请参见英文原版的 Git 仓库.
|
||||
|
||||
:翻译:
|
||||
.. line-block::
|
||||
|
||||
- `Google 开源项目风格指南 - 中文版 <https://github.com/zh-google-styleguide/zh-google-styleguide>`_
|
||||
|
||||
:项目主页:
|
||||
|
||||
- `Google Style Guide <https://google-styleguide.googlecode.com>`_
|
||||
@ -30,7 +30,7 @@ TypeScript 代码必须使用路径进行导入。这里的路径既可以是相
|
||||
|
||||
在 TypeScript 有两种组织代码的方式：命名空间（namespace）和模块（module）。
|
||||
|
||||
不允许使用命名空间，在 TypeScript 中必须使用模块（即 `ES6 模块 <http://exploringjs.com/es6/ch_modules.html>`_ ）。也就是说，在引用其它文件中的代码时必须以 ``import {foo} from 'bar'`` 的形式进行导入和导出。
|
||||
不允许使用命名空间，在 TypeScript 中必须使用模块（即 `ES6 模块 <https://exploringjs.com/es6/ch_modules.html>`_ ）。也就是说，在引用其它文件中的代码时必须以 ``import {foo} from 'bar'`` 的形式进行导入和导出。
|
||||
|
||||
不允许使用 ``namespace Foo { ... }`` 的形式组织代码。命名空间只能在所用的外部第三方库有要求时才能使用。如果需要在语义上对代码划分命名空间，应当通过分成不同文件的方式实现。
|
||||
|
||||
|
||||
@ -275,7 +275,7 @@ TypeScript 支持使用 `类型别名 <https://www.typescriptlang.org/docs/handb
|
||||
// 应当这样做！
|
||||
const users: {[userName: string]: number} = ...;
|
||||
|
||||
然而，相比使用上面的这种形式，在 TypeScript 中应当考虑使用 ES6 新增的 ``Map`` 与 ``Set`` 类型。因为 JavaScript 对象有一些 `令人困惑又不符合预期的行为 <http://2ality.com/2012/01/objects-as-maps.html>`_ ，而 ES6 的新增类型能够更明确地表达程序员的设计思路。此外， ``Map`` 类型的键和 ``Set`` 类型的元素都允许使用 ``string`` 以外的其他类型。
|
||||
然而，相比使用上面的这种形式，在 TypeScript 中应当考虑使用 ES6 新增的 ``Map`` 与 ``Set`` 类型。因为 JavaScript 对象有一些 `令人困惑又不符合预期的行为 <https://2ality.com/2012/01/objects-as-maps.html>`_ ，而 ES6 的新增类型能够更明确地表达程序员的设计思路。此外， ``Map`` 类型的键和 ``Set`` 类型的元素都允许使用 ``string`` 以外的其他类型。
|
||||
|
||||
TypeScript 内建的 ``Record<Keys, ValueType>`` 允许使用已定义的一组键创建类型。它与关联数组的不同之处在于键是静态确定的。关于它的使用建议，参见 :ref:`ts-mapped-conditional-types` 一节。
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user