diff --git a/README.rst b/README.rst index c914cb1..324275f 100644 --- a/README.rst +++ b/README.rst @@ -21,24 +21,28 @@ Google 开源项目风格指南——中文版 英文版项目维护的是在 Google 使用的编程风格指南。如果你正在修改的项目源自 Google，你可能会被引导至英文版项目页面，以了解项目所使用的风格。 -我们已经发布了七份 **中文版** 的风格指南: +我们已经发布了 **9** 份 **中文版** 的风格指南: -#. `Google C++ 风格指南 `_ +#. `Google C++ 风格指南 `_ -#. `Google Objective-C 风格指南 `_ +#. `Google Objective-C 风格指南 `_ -#. `Google Python 风格指南 `_ +#. `Google Python 风格指南 `_ #. `Google JavaScript 风格指南 `_ -#. `Google Shell 风格指南 `_ +#. `Google Shell 风格指南 `_ #. `Google JSON 风格指南 `_ #. `Google TypeScript 风格指南 `_ +#. `Google HTML/CSS 风格指南 `_ + +#. `Google Java 风格指南 `_ + 中文版项目采用 reStructuredText 纯文本标记语法，并使用 Sphinx 生成 HTML / CHM / PDF 等文档格式。 * 英文版项目还包含 `cpplint `_ ——一个用来帮助适应风格准则的工具，以及 `google-c-style.el `_，Google 风格的 Emacs 配置文件。 -* 另外，招募志愿者翻译 `XML Document Format Style Guide `_ ，有意者请联系 `Yang.Y `_ 。 +* 另外，招募志愿者翻译 `XML Document Format Style Guide `_ ，有意者请联系 `Yang.Y `_ 。 diff --git a/google-cpp-styleguide/classes.rst b/google-cpp-styleguide/classes.rst index f9bfb2b..cda14fa 100644 --- a/google-cpp-styleguide/classes.rst +++ b/google-cpp-styleguide/classes.rst @@ -252,7 +252,7 @@ C++ 中 ``struct`` 和 ``class`` 关键字的含义几乎一样. 我们自己为 **定义** -用户可以使用 ``operator`` 关键字来 `重载内置运算符 `_ , 前提是其中一个参数是用户自定义类型. 用户还可以使用 ``operator""`` 定义一类新的字面量, 或者定义类型转换函数 (例如 ``operator bool()``). +用户可以使用 ``operator`` 关键字来 `重载内置运算符 `_ , 前提是其中一个参数是用户自定义类型. 用户还可以使用 ``operator""`` 定义一类新的字面量, 或者定义类型转换函数 (例如 ``operator bool()``). **优点** diff --git a/google-cpp-styleguide/formatting.rst b/google-cpp-styleguide/formatting.rst index 0c42524..a4a038c 100644 --- a/google-cpp-styleguide/formatting.rst +++ b/google-cpp-styleguide/formatting.rst @@ -862,9 +862,9 @@ Lambda 表达式对形参和函数体的格式化和其他函数一致; 捕获 #. 80 行限制事实上有助于避免代码可读性失控, 比如超多重嵌套块, 超多重函数调用等等. #. Linux 上设置好了 Locale 就几乎一劳永逸设置好所有开发环境的编码, 不像奇葩的 Windows. -#. Google 强调有一对 if-else 时, 不论有没有嵌套, 都要有大括号. Apple 正好 `有栽过跟头 `_ . +#. Google 强调有一对 if-else 时, 不论有没有嵌套, 都要有大括号. Apple 正好 `有栽过跟头 `_ . #. 其实我主张指针／地址操作符与变量名紧邻, ``int* a, b`` vs ``int *a, b``, 新手会误以为前者的 ``b`` 是 ``int *`` 变量, 但后者就不一样了, 高下立判. -#. 在这风格指南里我才刚知道 C++ 原来还有所谓的 `Alternative operator representations `_, 大概没人用吧. +#. 在这风格指南里我才刚知道 C++ 原来还有所谓的 `Alternative operator representations `_, 大概没人用吧. #. 注意构造函数初始值列表（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? `_ 来看, ``return;`` 比 ``return ;`` 更约定俗成（事实上 cpplint 会对后者报错, 指出分号前有多余的空格）, 且可用来提前跳出函数栈. +#. 本风格指南没有明确规定 void 函数里要不要用 return 语句, 不过就 Google 开源项目 leveldb 并没有写; 此外从 `Is a blank return statement at the end of a function whos return type is void necessary? `_ 来看, ``return;`` 比 ``return ;`` 更约定俗成（事实上 cpplint 会对后者报错, 指出分号前有多余的空格）, 且可用来提前跳出函数栈. diff --git a/google-cpp-styleguide/functions.rst b/google-cpp-styleguide/functions.rst index 003b06d..61463ac 100644 --- a/google-cpp-styleguide/functions.rst +++ b/google-cpp-styleguide/functions.rst @@ -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. 编写简短函数 ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/google-cpp-styleguide/index.rst b/google-cpp-styleguide/index.rst index 0d6f79f..4f7c474 100644 --- a/google-cpp-styleguide/index.rst +++ b/google-cpp-styleguide/index.rst @@ -17,16 +17,16 @@ .. line-block:: - `YuleFox `_ + `YuleFox `_ `Yang.Y `_ - `acgtyrant `_ - `lilinsanity `_ + `acgtyrant `_ + `lilinsanity `_ `楼宇 `_ :项目主页: - - `Google Style Guide `_ - - `Google 开源项目风格指南 - 中文版 `_ + - `Google Style Guide `_ + - `Google 开源项目风格指南 - 中文版 `_ 译者前言 -------------------- @@ -55,11 +55,11 @@ Google 经常会发布一些开源项目, 意味着会接受来自其他代码 - 2009-06 3.133 : YuleFox 的 1.0 版已经相当完善, 但原版在近一年的时间里, 其规范也发生了一些变化. - Yang.Y 与 YuleFox 一拍即合, 以项目的形式来延续中文版 : `Google 开源项目风格指南 - 中文版项目 `_. + Yang.Y 与 YuleFox 一拍即合, 以项目的形式来延续中文版 : `Google 开源项目风格指南 - 中文版项目 `_. 主要变化是同步到 3.133 最新英文版本, 做部分勘误和改善可读性方面的修改, 并改进排版效果. Yang.Y 重新翻修, YuleFox 做后续评审. - - 2008-07 1.0 : 出自 `YuleFox 的 Blog `_, 很多地方摘录的也是该版本. + - 2008-07 1.0 : 出自 `YuleFox 的 Blog `_, 很多地方摘录的也是该版本. 以下是正文. diff --git a/google-cpp-styleguide/magic.rst b/google-cpp-styleguide/magic.rst index 457df13..c918913 100644 --- a/google-cpp-styleguide/magic.rst +++ b/google-cpp-styleguide/magic.rst @@ -14,7 +14,7 @@ Google 用了很多自己实现的技巧 / 工具使 C++ 代码更加健壮, 我 所有权是一种登记／管理动态内存和其它资源的技术. 动态分配对象的所有主是一个对象或函数, 后者负责确保当前者无用时就自动销毁前者. 所有权有时可以共享, 此时就由最后一个所有主来负责销毁它. 甚至也可以不用共享, 在代码中直接把所有权传递给其它对象. -智能指针是一个通过重载 ``*`` 和 ``->`` 运算符以表现得如指针一样的类. 智能指针类型被用来自动化所有权的登记工作, 来确保执行销毁义务到位. `std::unique_ptr `_ 是 C++11 新推出的一种智能指针类型, 用来表示动态分配出的对象的独一无二的所有权; 当 ``std::unique_ptr`` 离开作用域时, 对象就会被销毁. ``std::unique_ptr`` 不能被复制, 但可以把它移动（move）给新所有主. `std::shared_ptr `_ 同样表示动态分配对象的所有权, 但可以被共享, 也可以被复制; 对象的所有权由所有复制者共同拥有, 最后一个复制者被销毁时, 对象也会随着被销毁. +智能指针是一个通过重载 ``*`` 和 ``->`` 运算符以表现得如指针一样的类. 智能指针类型被用来自动化所有权的登记工作, 来确保执行销毁义务到位. `std::unique_ptr `_ 是 C++11 新推出的一种智能指针类型, 用来表示动态分配出的对象的独一无二的所有权; 当 ``std::unique_ptr`` 离开作用域时, 对象就会被销毁. ``std::unique_ptr`` 不能被复制, 但可以把它移动（move）给新所有主. `std::shared_ptr `_ 同样表示动态分配对象的所有权, 但可以被共享, 也可以被复制; 对象的所有权由所有复制者共同拥有, 最后一个复制者被销毁时, 对象也会随着被销毁. **> 优点** @@ -74,7 +74,7 @@ Google 用了很多自己实现的技巧 / 工具使 C++ 代码更加健壮, 我 ``cpplint.py`` 是一个用来分析源文件, 能检查出多种风格错误的工具. 它不并完美, 甚至还会漏报和误报, 但它仍然是一个非常有用的工具. 在行尾加 ``// NOLINT``, 或在上一行加 ``// NOLINTNEXTLINE``, 可以忽略报错. -某些项目会指导你如何使用他们的项目工具运行 ``cpplint.py``. 如果你参与的项目没有提供, 你可以单独下载 `cpplint.py `_. +某些项目会指导你如何使用他们的项目工具运行 ``cpplint.py``. 如果你参与的项目没有提供, 你可以单独下载 `cpplint.py `_. 译者（acgtyrant）笔记 diff --git a/google-cpp-styleguide/naming.rst b/google-cpp-styleguide/naming.rst index 0a0d791..362c44c 100644 --- a/google-cpp-styleguide/naming.rst +++ b/google-cpp-styleguide/naming.rst @@ -161,7 +161,7 @@ C++ 文件要以 ``.cc`` 结尾, 头文件以 ``.h`` 结尾. 专门插入文本 **说明** -所有具有静态存储类型的变量 (例如静态变量或全局变量, 参见 `存储类型 `_) 都应当以此方式命名. 对于其他存储类型的变量, 如自动变量等, 这条规则是可选的. 如果不采用这条规则, 就按照一般的变量命名规则. +所有具有静态存储类型的变量 (例如静态变量或全局变量, 参见 `存储类型 `_) 都应当以此方式命名. 对于其他存储类型的变量, 如自动变量等, 这条规则是可选的. 如果不采用这条规则, 就按照一般的变量命名规则. .. _function-names: diff --git a/google-cpp-styleguide/others.rst b/google-cpp-styleguide/others.rst index 3cb2605..880aff7 100644 --- a/google-cpp-styleguide/others.rst +++ b/google-cpp-styleguide/others.rst @@ -629,7 +629,7 @@ auto x(3); // 圆括号。 auto y{3}; // 大括号。 - 它们不是同一回事——``x`` 是 ``int``, ``y`` 则是 ``std::initializer_list``. 其它一般不可见的代理类型（acgtyrant 注：normally-invisible proxy types, 它涉及到 C++ 鲜为人知的坑：`Why is vector not a STL container? `_）也有大同小异的陷阱。 + 它们不是同一回事——``x`` 是 ``int``, ``y`` 则是 ``std::initializer_list``. 其它一般不可见的代理类型（acgtyrant 注：normally-invisible proxy types, 它涉及到 C++ 鲜为人知的坑：`Why is vector not a STL container? `_）也有大同小异的陷阱。 如果在接口里用 ``auto``, 比如声明头文件里的一个常量，那么只要仅仅因为程序员一时修改其值而导致类型变化的话——API 要翻天覆地了。 @@ -882,7 +882,7 @@ 定义: - `Boost 库集 `_ 是一个广受欢迎, 经过同行鉴定, 免费开源的 C++ 库集. + `Boost 库集 `_ 是一个广受欢迎, 经过同行鉴定, 免费开源的 C++ 库集. 优点: @@ -896,35 +896,35 @@ 为了向阅读和维护代码的人员提供更好的可读性, 我们只允许使用 Boost 一部分经认可的特性子集. 目前允许使用以下库: - - `Call Traits `_ : ``boost/call_traits.hpp`` + - `Call Traits `_ : ``boost/call_traits.hpp`` - - `Compressed Pair `_ : ``boost/compressed_pair.hpp`` + - `Compressed Pair `_ : ``boost/compressed_pair.hpp`` - - ``_ : ``boost/graph``, except serialization (``adj_list_serialize.hpp``) and parallel/distributed algorithms and data structures(``boost/graph/parallel/*`` and ``boost/graph/distributed/*``) + - ``_ : ``boost/graph``, except serialization (``adj_list_serialize.hpp``) and parallel/distributed algorithms and data structures(``boost/graph/parallel/*`` and ``boost/graph/distributed/*``) - - `Property Map `_ : ``boost/property_map.hpp`` + - `Property Map `_ : ``boost/property_map.hpp`` - - The part of `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 `_ 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 `_ 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 `_ 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 `_ : ``boost/bimap`` + - `Bimap `_ : ``boost/bimap`` - - `Statistical Distributions and Functions `_ : ``boost/math/distributions`` + - `Statistical Distributions and Functions `_ : ``boost/math/distributions`` - - `Multi-index `_ : ``boost/multi_index`` + - `Multi-index `_ : ``boost/multi_index`` - - `Heap `_ : ``boost/heap`` + - `Heap `_ : ``boost/heap`` - - The flat containers from `Container `_: ``boost/container/flat_map``, and ``boost/container/flat_set`` + - The flat containers from `Container `_: ``boost/container/flat_map``, and ``boost/container/flat_set`` 我们正在积极考虑增加其它 Boost 特性, 所以列表中的规则将不断变化. 以下库可以用，但由于如今已经被 C++ 11 标准库取代，不再鼓励： - - `Pointer Container `_ : ``boost/ptr_container``, 改用 `std::unique_ptr `_ + - `Pointer Container `_ : ``boost/ptr_container``, 改用 `std::unique_ptr `_ - - `Array `_ : ``boost/array.hpp``, 改用 `std::array `_ + - `Array `_ : ``boost/array.hpp``, 改用 `std::array `_ 6.23. C++11 ~~~~~~~~~~~~~~~~~~~~~~ @@ -959,14 +959,14 @@ 译者（acgtyrant）笔记 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. 实际上，`缺省参数会改变函数签名的前提是改变了它接收的参数数量 `_，比如把 ``void a()`` 改成 ``void a(int b = 0)``, 开发者改变其代码的初衷也许是，在不改变「代码兼容性」的同时，又提供了可选 int 参数的余地，然而这终究会破坏函数指针上的兼容性，毕竟函数签名确实变了。 +#. 实际上，`缺省参数会改变函数签名的前提是改变了它接收的参数数量 `_，比如把 ``void a()`` 改成 ``void a(int b = 0)``, 开发者改变其代码的初衷也许是，在不改变「代码兼容性」的同时，又提供了可选 int 参数的余地，然而这终究会破坏函数指针上的兼容性，毕竟函数签名确实变了。 #. 此外把自带缺省参数的函数地址赋值给指针时，会丢失缺省参数信息。 -#. 我还发现 `滥用缺省参数会害得读者光只看调用代码的话，会误以为其函数接受的参数数量比实际上还要少。 `_ +#. 我还发现 `滥用缺省参数会害得读者光只看调用代码的话，会误以为其函数接受的参数数量比实际上还要少。 `_ #. ``friend`` 实际上只对函数／类赋予了对其所在类的访问权限，并不是有效的声明语句。所以除了在头文件类内部写 friend 函数／类，还要在类作用域之外正式地声明一遍，最后在对应的 ``.cc`` 文件加以定义。 #. 本风格指南都强调了「友元应该定义在同一文件内，避免代码读者跑到其它文件查找使用该私有成员的类」。那么可以把其声明放在类声明所在的头文件，定义也放在类定义所在的文件。 #. 由于友元函数／类并不是类的一部分，自然也不会是类可调用的公有接口，于是我主张全集中放在类的尾部，即的数据成员之后，参考 :ref:`声明顺序 ` 。 -#. `对使用 C++ 异常处理应具有怎样的态度？ `_ 非常值得一读。 +#. `对使用 C++ 异常处理应具有怎样的态度？ `_ 非常值得一读。 #. 注意初始化 const 对象时，必须在初始化的同时值初始化。 #. 用断言代替无符号整型类型，深有启发。 #. auto 在涉及迭代器的循环语句里挺常用。 -#. `Should the trailing return type syntax style become the default for new C++11 programs? `_ 讨论了 auto 与尾置返回类型一起用的全新编码风格，值得一看。 +#. `Should the trailing return type syntax style become the default for new C++11 programs? `_ 讨论了 auto 与尾置返回类型一起用的全新编码风格，值得一看。 diff --git a/google-cpp-styleguide/scoping.rst b/google-cpp-styleguide/scoping.rst index db1996e..46c3b42 100644 --- a/google-cpp-styleguide/scoping.rst +++ b/google-cpp-styleguide/scoping.rst @@ -268,7 +268,7 @@ .. tip:: - 禁止使用 `静态储存周期 (static storage duration) `_ 的变量, 除非它们可以 `平凡地析构 (trivially destructible) `_. 简单来说, 就是析构函数 (destructor) 不会做任何事情, 包括成员和基类 (base) 的析构函数. 正式地说, 就是这一类型 (type) 没有用户定义的析构函数或虚析构函数 (virtual destructor), 且所有成员和基类也能平凡地析构. 函数的局部静态变量可以动态地初始化 (dynamic initialization) . 除了少数情况外, 不推荐动态初始化静态类成员变量或命名空间内的变量. 详情参见下文. + 禁止使用 `静态储存周期 (static storage duration) `_ 的变量, 除非它们可以 `平凡地析构 (trivially destructible) `_. 简单来说, 就是析构函数 (destructor) 不会做任何事情, 包括成员和基类 (base) 的析构函数. 正式地说, 就是这一类型 (type) 没有用户定义的析构函数或虚析构函数 (virtual destructor), 且所有成员和基类也能平凡地析构. 函数的局部静态变量可以动态地初始化 (dynamic initialization) . 除了少数情况外, 不推荐动态初始化静态类成员变量或命名空间内的变量. 详情参见下文. 作为经验之谈: 若只看全局变量的声明, 如果该语句可以作为常量表达式 (constexpr), 则满足以上要求. diff --git a/google-html-css-styleguide/css_formatting_rules.rst b/google-html-css-styleguide/css_formatting_rules.rst index c817f3c..a0b5961 100644 --- a/google-html-css-styleguide/css_formatting_rules.rst +++ b/google-html-css-styleguide/css_formatting_rules.rst @@ -26,7 +26,7 @@ css文件书写按字母顺序排列的方式，容易记忆和维护，以达 缩进块内容。 -将包括嵌套及声明的 `块内容 `_ 进行缩进，以体现层次并提高可读性。 +将包括嵌套及声明的 `块内容 `_ 进行缩进，以体现层次并提高可读性。 .. code-block:: css @@ -84,7 +84,7 @@ CSS属性名结束 在选择器和后面的声明块之间使用一个空格。 -最后一个选择器与表示 `声名块 `_ 开始的左大花括号在同行，中间有一个字符空格。 +最后一个选择器与表示 `声名块 `_ 开始的左大花括号在同行，中间有一个字符空格。 表示开始的左大花括号和选择器在同行。 @@ -157,7 +157,7 @@ CSS引号 在属性选择器及属性值中使用单引号（''）而不是双引号（""）。在 ``url（）`` 中不要使用引号。 -特例：如果你确实需要定义 ``@charset`` ，由于 `不允许使用单引号 `_ ，故请使用双引号。 +特例：如果你确实需要定义 ``@charset`` ，由于 `不允许使用单引号 `_ ，故请使用双引号。 .. code-block:: css diff --git a/google-html-css-styleguide/css_style_rules.rst b/google-html-css-styleguide/css_style_rules.rst index ce4d275..fd9c6cc 100644 --- a/google-html-css-styleguide/css_style_rules.rst +++ b/google-html-css-styleguide/css_style_rules.rst @@ -8,7 +8,7 @@ CSS有效性 使用有效的CSS代码，除非在处理css验证器bug或者是专有的语法时。 -使用诸如 `W3C CSS validator `_ 等工具验证测试。 +使用诸如 `W3C CSS validator `_ 等工具验证测试。 使用有效的CSS代码是一个可衡量CSS代码质量的指标，可帮你找出不起作用可被删除的CSS代码，从而确保CSS的合理使用。 @@ -70,7 +70,7 @@ ID和class命名要尽可能简短，但必要的话就别怕长。 除了必要情况下（例如辅助的类），不要将元素与id或class名称结合做为选择器。 -避免不必要的祖先选择器也是出于 `性能原因 `_ 的考虑。 +避免不必要的祖先选择器也是出于 `性能原因 `_ 的考虑。 .. code-block:: css @@ -87,7 +87,7 @@ ID和class命名要尽可能简短，但必要的话就别怕长。 尽可能使用简写的属性书写方式。 -CSS提供了多种属性 `简写 `_ 的方式（如 ``font`` ），即使只显式设置一个值，也应该尽可能地使用。 +CSS提供了多种属性 `简写 `_ 的方式（如 ``font`` ），即使只显式设置一个值，也应该尽可能地使用。 使用简写属性有助于提高代码效率及可读性。 diff --git a/google-html-css-styleguide/general_meta_rules.rst b/google-html-css-styleguide/general_meta_rules.rst index c7373c2..63177cf 100644 --- a/google-html-css-styleguide/general_meta_rules.rst +++ b/google-html-css-styleguide/general_meta_rules.rst @@ -10,7 +10,7 @@ 在HTML模板和文档中使用 ```` 指定编码。不需要为样式表指定编码，它默认是UTF-8。 -（想了解更多关于应该何时并如何指定编码，请查看 `Handling character encodings in HTML and CSS `_） +（想了解更多关于应该何时并如何指定编码，请查看 `Handling character encodings in HTML and CSS `_） 注释 -------- diff --git a/google-html-css-styleguide/general_style_rules.rst b/google-html-css-styleguide/general_style_rules.rst index 9e919d1..a2728b1 100644 --- a/google-html-css-styleguide/general_style_rules.rst +++ b/google-html-css-styleguide/general_style_rules.rst @@ -12,7 +12,7 @@ .. code-block:: html - + @@ -21,7 +21,7 @@ /* 不推荐 */ .example { - background: url(http://www.google.com/images/example); + background: url(https://www.google.com/images/example); } /* 推荐 */ diff --git a/google-html-css-styleguide/html_style_rules.rst b/google-html-css-styleguide/html_style_rules.rst index 696273c..3a40c5b 100644 --- a/google-html-css-styleguide/html_style_rules.rst +++ b/google-html-css-styleguide/html_style_rules.rst @@ -8,7 +8,7 @@ HTML样式规则 HTML5（HTML语法）是所有HTML文档的首选： ```` 。 -（推荐使用HTML，即text/html。不要使用XHTML。XHTML，即 `application/xhtml+xml `_，缺乏浏览器和基础结构的支持，并且优化的空间比HTML小。） +（推荐使用HTML，即text/html。不要使用XHTML。XHTML，即 `application/xhtml+xml `_，缺乏浏览器和基础结构的支持，并且优化的空间比HTML小。） 虽然HTML闭合标签没有问题，但是不要自闭合空标签。即写 ``
`` 而不是 ``
`` 。 @@ -19,7 +19,7 @@ HTML合法性 使用合法的HTML代码，除非由于文件大小导致的不可达到的性能目标而不能使用。 -利用已用工具对合法性进行测试，例如 `W3C HTML validator `_。 +利用已用工具对合法性进行测试，例如 `W3C HTML validator `_。 使用合法的HTML是一个可度量的基准质量属性，该属性有助于了解技术需求和约束，从而确保合理的HTML使用。 @@ -129,7 +129,7 @@ HTML合法性 省略可选的标签（可选）。 -为了优化文件大小和可扫描，考虑省略可选标签。 `HTML5规范 `_ 定义了哪些标签可以被省略。 +为了优化文件大小和可扫描，考虑省略可选标签。 `HTML5规范 `_ 定义了哪些标签可以被省略。 （这种方法可能要求一段宽限期去建立一个更加广泛的准则，因为它和Web开发人员通常所了解的有着显著不同。考虑到一致性和简单性，最好省略所有可选标签。） @@ -158,7 +158,7 @@ type属性 引用样式表（除非不是使用CSS）和脚本（除非不是使用JavaScript）不要使用type属性。 -HTML5将 `text/css `_ 和 `text/javascript `_ 设置为默认值，在这种情况下指定type属性并不必要。甚至同样兼容老版本的浏览器。 +HTML5将 `text/css `_ 和 `text/javascript `_ 设置为默认值，在这种情况下指定type属性并不必要。甚至同样兼容老版本的浏览器。 .. code-block:: html diff --git a/google-html-css-styleguide/index.rst b/google-html-css-styleguide/index.rst new file mode 100644 index 0000000..d96d2d0 --- /dev/null +++ b/google-html-css-styleguide/index.rst @@ -0,0 +1,16 @@ +0. 扉页 +============ + +:原作者: + .. line-block:: + + 详细作者列表请参见英文原版的 Git 仓库. + +:翻译: + .. line-block:: + + - `Google 开源项目风格指南 - 中文版 `_ + +:项目主页: + + - `Google Style Guide `_ diff --git a/google-java-styleguide/index.rst b/google-java-styleguide/index.rst index e063e16..5eb94c8 100644 --- a/google-java-styleguide/index.rst +++ b/google-java-styleguide/index.rst @@ -15,5 +15,5 @@ :项目主页: - - `Google Style Guide `_ - - `Google 开源项目风格指南 - 中文版 `_ \ No newline at end of file + - `Google Style Guide `_ + - `Google 开源项目风格指南 - 中文版 `_ diff --git a/google-javascript-styleguide/index.rst b/google-javascript-styleguide/index.rst new file mode 100644 index 0000000..24c0c2a --- /dev/null +++ b/google-javascript-styleguide/index.rst @@ -0,0 +1,17 @@ +0. 扉页 +============ + +:原作者: + .. line-block:: + + 详细作者列表请参见英文原版的 Git 仓库. + +:翻译: + .. line-block:: + + - `Google 开源项目风格指南 - 中文版 `_ + +:项目主页: + + - `Google Style Guide `_ + diff --git a/google-javascript-styleguide/javascript_language_rules.rst b/google-javascript-styleguide/javascript_language_rules.rst index 8156556..47f927e 100644 --- a/google-javascript-styleguide/javascript_language_rules.rst +++ b/google-javascript-styleguide/javascript_language_rules.rst @@ -150,7 +150,7 @@ js语句要求以分号结尾，除非能够正确地推断分号的位置。在 function foo() {} } -虽然大多数脚本引擎支持功能区块内声明，但ECMAScript并未认可（见 `ECMA-262 `_ ，第13条和第14）。若与他人的及EcmaScript所建议的不一致，即可视为不好的实现方式。ECMAScript只允许函数声明语句列表, 在根语句列表脚本或者函数。相反，使用一个变量初始化函数表达式在块内定义一个函数块： +虽然大多数脚本引擎支持功能区块内声明，但ECMAScript并未认可（见 `ECMA-262 `_ ，第13条和第14）。若与他人的及EcmaScript所建议的不一致，即可视为不好的实现方式。ECMAScript只允许函数声明语句列表, 在根语句列表脚本或者函数。相反，使用一个变量初始化函数表达式在块内定义一个函数块： :: @@ -279,7 +279,7 @@ js语句要求以分号结尾，除非能够正确地推断分号的位置。在 可以使用，但是要小心。 -创建闭包可能是JS最有用的和经常被忽视的功能。在 `这里 `_ 很好地描述说明了闭包的工作。 +创建闭包可能是JS最有用的和经常被忽视的功能。在 `这里 `_ 很好地描述说明了闭包的工作。 要记住的一件事情，一个闭包的指针指向包含它的范围。因此，附加一个闭包的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; diff --git a/google-javascript-styleguide/javascript_style_rules.rst b/google-javascript-styleguide/javascript_style_rules.rst index a08aa7a..f288ca0 100644 --- a/google-javascript-styleguide/javascript_style_rules.rst +++ b/google-javascript-styleguide/javascript_style_rules.rst @@ -13,7 +13,7 @@ Javascript风格规范 * *保护* 属性和方法应该以无下划线开头命名（像公共属性和方法一样）。 -了解更多关于私有成员和保护成员的信息，请阅读 `可见性 `_ 部分。 +了解更多关于私有成员和保护成员的信息，请阅读 `可见性 `_ 部分。 方法和函数参数 ~~~~~~~~~~~~~~~~~ @@ -62,7 +62,7 @@ JavaScript没有原生的对封装和命名空间的支持。 ... }; -很多JavaScript库，包括 `the Closure Library `_ 和 `Dojo toolkit `_ 给你高级功能来声明命名空间。保持你的命名空间声明一致。 +很多JavaScript库，包括 `the Closure Library `_ 和 `Dojo toolkit `_ 给你高级功能来声明命名空间。保持你的命名空间声明一致。 :: @@ -135,7 +135,7 @@ JavaScript没有原生的对封装和命名空间的支持。 staticHelper(new MyClass()); }; -不要为命名空间起本地别名。命名空间应该只能使用 `goog.scope `_ 命名别名。 +不要为命名空间起本地别名。命名空间应该只能使用 `goog.scope `_ 命名别名。 :: @@ -202,7 +202,7 @@ JavaScript没有原生的对封装和命名空间的支持。 代码格式 ---------- -我们原则上遵循 `C++格式规范 `_ ，并且进行以下额外的说明。 +我们原则上遵循 `C++格式规范 `_ ，并且进行以下额外的说明。 大括号 ~~~~~~~~ @@ -400,7 +400,7 @@ JavaScript没有原生的对封装和命名空间的支持。 更多的缩进 ~~~~~~~~~~~~ -事实上，除了 `初始化数组和对象 `_ 和传递匿名函数外，所有被拆开的多行文本应与之前的表达式左对齐，或者以4个（而不是2个）空格作为一缩进层次。 +事实上，除了 `初始化数组和对象 `_ 和传递匿名函数外，所有被拆开的多行文本应与之前的表达式左对齐，或者以4个（而不是2个）空格作为一缩进层次。 :: @@ -591,7 +591,7 @@ JavaScript类型 鼓励和强制执行的编译器。 -JSDoc记录类型时，要尽可能具体和准确。我们支持的类型是基于 `EcmaScript 4规范 `_ 。 +JSDoc记录类型时，要尽可能具体和准确。我们支持的类型是基于 `EcmaScript 4规范 `_ 。 JavaScript类型语言 ~~~~~~~~~~~~~~~~~~~ @@ -627,7 +627,7 @@ ES4提案包含指定JavaScript类型的语言。我们使用JsDoc这种语言 - * - 枚举类型 - ``{goog.events.EventType}`` 字面量初始化对象的属性之一 ``goog.events.EventType`` 。 - - 一个枚举必须被初始化为一个字面量对象，或作为另一个枚举的别名,加注 ``@enum`` JSDoc标记。这个属性是枚举实例。 `下面 `_ 是枚举语法的定义。 + - 一个枚举必须被初始化为一个字面量对象，或作为另一个枚举的别名,加注 ``@enum`` JSDoc标记。这个属性是枚举实例。 `下面 `_ 是枚举语法的定义。 请注意，这是我们的类型系统中为数不多的ES4规范以外的事情之一。 - @@ -704,13 +704,13 @@ ES4提案包含指定JavaScript类型的语言。我们使用JsDoc这种语言 带注释函数的可变数目参数。 - 指定带注释函数接受一个可变数目的参数。 - - * - 函数 `可选参数 `_ + * - 函数 `可选参数 `_ - ``{function(?string=, number=)}`` 一个函数，它接受一个可选的、可以为空的字符串和一个可选的数字作为参数。“=”只用于函数类型声明。 - 指定函数的可选参数。 - - * - 函数 `可选参数 `_ （ ``@param`` 注释） + * - 函数 `可选参数 `_ （ ``@param`` 注释） - ``@param {number=} opt_argument`` ``number`` 类型的可选参数。 @@ -748,7 +748,7 @@ JavaScript中的类型 - :: new Number(true) - - `Number对象 `_ + - `Number对象 `_ * - string - :: @@ -761,7 +761,7 @@ JavaScript中的类型 new String('Hello') new String(42) - - `String对象 `_ + - `String对象 `_ * - boolean - :: @@ -773,7 +773,7 @@ JavaScript中的类型 - :: new Boolean(true) - - `Boolean对象 `_ + - `Boolean对象 `_ * - RegExp - :: @@ -843,7 +843,7 @@ JavaScript中的类型 function(x, y) { return x * y; } - - `Function对象 `_ + - `Function对象 `_ * - function(number, number): number - :: @@ -1053,8 +1053,8 @@ JavaScript中的类型 使用JSDoc。 -我们使用 `c++的注释风格 `_ 。 -所有的文件、类、方法和属性都应该用合适的 `JSDoc `_ 的 `标签 `_ 和 `类型 `_ 注释。除了直观的方法名称和参数名称外，方法的描述、方法的参数以及方法的返回值也要包含进去。 +我们使用 `c++的注释风格 `_ 。 +所有的文件、类、方法和属性都应该用合适的 `JSDoc `_ 的 `标签 `_ 和 `类型 `_ 注释。除了直观的方法名称和参数名称外，方法的描述、方法的参数以及方法的返回值也要包含进去。 行内注释应该使用 ``//`` 的形式。 @@ -1063,7 +1063,7 @@ JavaScript中的类型 注释语法 ~~~~~~~~~~ -JSDoc的语法基于 `JavaDoc `_ ，许多编译工具从JSDoc注释中获取信息从而进行代码验证和优化，所以这些注释必须符合语法规则。 +JSDoc的语法基于 `JavaDoc `_ ，许多编译工具从JSDoc注释中获取信息从而进行代码验证和优化，所以这些注释必须符合语法规则。 :: @@ -1143,12 +1143,12 @@ JSDoc中的HTML * */ -`JavaDoc `_ 风格指南对于如何编写良好的doc注释是非常有帮助的。 +`JavaDoc `_ 风格指南对于如何编写良好的doc注释是非常有帮助的。 顶层/文件层注释 ~~~~~~~~~~~~~~~~~~ -`版权声明 `_ 和作者信息是可选的。顶层注释的目的是为了让不熟悉代码的读者了解文件中有什么。它需要描述文件内容，依赖关系以及兼容性的信息。例如： +`版权声明 `_ 和作者信息是可选的。顶层注释的目的是为了让不熟悉代码的读者了解文件中有什么。它需要描述文件内容，依赖关系以及兼容性的信息。例如： :: @@ -1160,7 +1160,7 @@ JSDoc中的HTML Class评论 ~~~~~~~~~~~ -类必须记录说明与描述和 `一个类型的标签 `_ ，标识的构造函数。类必须加以描述，若是构造函数则需标注出。 +类必须记录说明与描述和 `一个类型的标签 `_ ，标识的构造函数。类必须加以描述，若是构造函数则需标注出。 :: @@ -1278,7 +1278,7 @@ JSDoc标签参考 当一个方法被标记为 ``@const`` ，意味着这个方法不仅不可以被覆盖，而且也不能在子类中重写。 - ``@const`` 的更多信息，请看 `常量 `_ 部分 + ``@const`` 的更多信息，请看 `常量 `_ 部分 * - @constructor - @constructor @@ -1603,7 +1603,7 @@ JSDoc标签参考 }; - 给方法、函数、构造函数的参数添加文档说明。 - `参数类型 `_ 一定要写在大括号里。如果类型被省略，编译器将不做类型检测。 + `参数类型 `_ 一定要写在大括号里。如果类型被省略，编译器将不做类型检测。 * - @private - @private @private {type} @@ -1617,7 +1617,7 @@ JSDoc标签参考 * @private {!Array.} */ this.handlers\_ = []; - - 与方法或属性名结尾使用一个下划线来联合表明该成员是 `私有的 `_ 。随着工具对 ``@private`` 的认可，结尾的下划线可能最终被废弃。 + - 与方法或属性名结尾使用一个下划线来联合表明该成员是 `私有的 `_ 。随着工具对 ``@private`` 的认可，结尾的下划线可能最终被废弃。 * - @protected - @protected @protected {type} @@ -1635,7 +1635,7 @@ JSDoc标签参考 goog.ui.Component.prototype.setElementInternal = function(element) { // ... }; - - 用来表明成员或属性是 ``受保护的 ``_ 。成员或属性应使用没有跟随下划线的名称。 + - 用来表明成员或属性是 ``受保护的 ``_ 。成员或属性应使用没有跟随下划线的名称。 * - @return - @return {Type} Description @@ -1652,7 +1652,7 @@ JSDoc标签参考 }; - 在方法或函数调用时使用，来说明返回类型。给布尔值写注释时，写成类似“这个组件是否可见”比“如果组件可见则为true，否则为false”要好。如果没有返回值，不使用 ``@return`` 标签。 - `类型 `_ 名称必须包含在大括号内。如果省略类型，编译器将不会检查返回值的类型。 + `类型 `_ 名称必须包含在大括号内。如果省略类型，编译器将不会检查返回值的类型。 * - @see - @see Link @@ -1734,7 +1734,7 @@ JSDoc标签参考 goog.bind = function(fn, thisObj, var_args) { ... }; - - 这个注释可以用来声明一个 `模板类型名 `_ 。 + - 这个注释可以用来声明一个 `模板类型名 `_ 。 * - @this - @this Type @this {Type} @@ -1766,7 +1766,7 @@ JSDoc标签参考 * @type {string} */ var hexId = hexId; - - 标识变量，属性或表达式的 `类型 `_ 。大多数类型不需要大括号，但有些项目为了保持一致性而要求所有类型都使用大括号。 + - 标识变量，属性或表达式的 `类型 `_ 。大多数类型不需要大括号，但有些项目为了保持一致性而要求所有类型都使用大括号。 * - @typedef - @typedef @@ -1780,7 +1780,7 @@ JSDoc标签参考 goog.readNumber = function(x) { ... } - - 使用此注释来声明一个更 `复杂的类型 `_ 的别名。 + - 使用此注释来声明一个更 `复杂的类型 `_ 的别名。 你也许在第三方代码中看到其他类型JSDoc注释，这些注释出现在 `JSDoc Toolkit标签的参考 `_ ，但目前在谷歌的代码中不鼓励使用。你应该将他们当作“保留”字，他们包括： diff --git a/google-objc-styleguide/comments.rst b/google-objc-styleguide/comments.rst index f872356..e76eaf2 100644 --- a/google-objc-styleguide/comments.rst +++ b/google-objc-styleguide/comments.rst @@ -80,7 +80,7 @@ 当实例变量指向 ``CoreFoundation``、C++ 或者其它非 Objective-C 对象时，不论指针是否会被 ``retained``，都需要使用 ``__strong`` 和 ``__weak`` 类型修饰符明确指明。``CoreFoundation`` 和其它非 Objective-C 对象指针需要显式的内存管理，即便使用了自动引用计数或垃圾回收机制。当不允许使用 ``__weak`` 类型修饰符（比如，使用 clang 编译时的 C++ 成员变量），应使用注释替代说明。 -注意：Objective-C 对象中的 C++ 对象的自动封装，缺省是不允许的，参见 `这里 `_ 的说明。 +注意：Objective-C 对象中的 C++ 对象的自动封装，缺省是不允许的，参见 `这里 `_ 的说明。 强引用及弱引用声明的例子： diff --git a/google-objc-styleguide/features.rst b/google-objc-styleguide/features.rst index 2304eff..e022db9 100644 --- a/google-objc-styleguide/features.rst +++ b/google-objc-styleguide/features.rst @@ -99,7 +99,7 @@ Cocoa 和 Objective-C 特性 Objective-C 2.0 以前，如果你在私有的 ``@interface`` 中声明了某个方法，但在 ``@implementation`` 中忘记定义这个方法，编译器不会抱怨（这是因为你没有在其它的类别中实现这个私有的方法）。解决文案是将方法放进指定类别的 ``@implemenation`` 中。 -如果你在使用 Objective-C 2.0，相反你应该使用 `类扩展 `_ 来声明你的私有类别，例如： +如果你在使用 Objective-C 2.0，相反你应该使用 `类扩展 `_ 来声明你的私有类别，例如： .. code-block:: objc @@ -121,7 +121,7 @@ Objective-C 的类别可以用来将一个大的 ``@implementation`` 拆分成 基于你所包括的头文件的编程语言，选择使用 ``#import`` 或是 ``#include``： * 当包含一个使用 Objective-C、Objective-C++ 的头文件时，使用 ``#import`` 。 -* 当包含一个使用标准 C、C++ 头文件时，使用 ``#include``。头文件应该使用 `#define 保护 `_。 +* 当包含一个使用标准 C、C++ 头文件时，使用 ``#include``。头文件应该使用 `#define 保护 `_。 一些 Objective-C 的头文件缺少 ``#define`` 保护，需要使用 ``#import`` 的方式包含。由于 Objective-C 的头文件只会被 Objective-C 的源文件及头文件包含，广泛地使用 ``#import`` 是可以的。 @@ -326,7 +326,7 @@ nil 检查 -使用 ``nil`` 的检查来检查应用程序的逻辑流程，而不是避免崩溃。Objective-C 运行时会处理向 ``nil`` 对象发送消息的情况。如果方法没有返回值，就没关系。如果有返回值，可能由于运行时架构、返回值类型以及 OS X 版本的不同而不同，参见 `Apple’s documentation `_ 。 +使用 ``nil`` 的检查来检查应用程序的逻辑流程，而不是避免崩溃。Objective-C 运行时会处理向 ``nil`` 对象发送消息的情况。如果方法没有返回值，就没关系。如果有返回值，可能由于运行时架构、返回值类型以及 OS X 版本的不同而不同，参见 `Apple’s documentation `_ 。 注意，这和 C/C++ 中检查指针是否为 ‵‵NULL`` 很不一样，C/C++ 运行时不做任何检查，从而导致应用程序崩溃。因此你仍然需要保证你不会对一个 C/C++ 的空指针解引用。 diff --git a/google-objc-styleguide/index.rst b/google-objc-styleguide/index.rst index 161ecfc..6a0e9bd 100644 --- a/google-objc-styleguide/index.rst +++ b/google-objc-styleguide/index.rst @@ -14,12 +14,12 @@ Google Objective-C Style Guide 中文版 :翻译: .. line-block:: - `ewangke `_ + `ewangke `_ `Yang.Y `_ :项目主页: - - `Google Style Guide `_ - - `Google 开源项目风格指南 - 中文版 `_ + - `Google Style Guide `_ + - `Google 开源项目风格指南 - 中文版 `_ 译者的话 @@ -28,7 +28,7 @@ Google Objective-C Style Guide 中文版 ewanke ^^^^^^^^^^^^ -一直想翻译这个 `style guide `_ ，终于在周末花了7个小时的时间用vim敲出了HTML。很多术语的翻译很难，平时看的中文技术类书籍有限，对很多术语的中文译法不是很清楚，难免有不恰当之处，请读者指出并帮我改进：王轲 ”ewangke at gmail.com” 2011.03.27 +一直想翻译这个 `style guide `_ ，终于在周末花了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 `_ +* `Apple’s Cocoa Coding Guidelines `_ -* `Google’s Open Source C++ Style Guide `_ +* `Google’s Open Source C++ Style Guide `_ .. note:: @@ -58,9 +58,9 @@ Cocoa 是 Mac OS X 上主要的应用程序框架之一。它由一组 Objective 本文档的目的在于为所有的 Mac OS X 的代码提供编码指南及实践。许多准则是在实际的项目和小组中经过长期的演化、验证的。Google 开发的开源项目遵从本指南的要求。 -Google 已经发布了遵守本指南开源代码，它们属于 `Google Toolbox for Mac project `_ 项目（本文以缩写 GTM 指代）。GTM 代码库中的代码通常为了可以在不同项目中复用。 +Google 已经发布了遵守本指南开源代码，它们属于 `Google Toolbox for Mac project `_ 项目（本文以缩写 GTM 指代）。GTM 代码库中的代码通常为了可以在不同项目中复用。 -注意，本指南不是 Objective-C 教程。我们假定读者对 Objective-C 非常熟悉。如果你刚刚接触 Objective-C 或者需要温习，请阅读 `The Objective-C Programming Language `_ 。 +注意，本指南不是 Objective-C 教程。我们假定读者对 Objective-C 非常熟悉。如果你刚刚接触 Objective-C 或者需要温习，请阅读 `The Objective-C Programming Language `_ 。 例子 ======== diff --git a/google-objc-styleguide/naming.rst b/google-objc-styleguide/naming.rst index f9b5cea..f558524 100644 --- a/google-objc-styleguide/naming.rst +++ b/google-objc-styleguide/naming.rst @@ -4,9 +4,9 @@ 对于易维护的代码而言，命名规则非常重要。Objective-C 的方法名往往十分长，但代码块读起来就像散文一样，不需要太多的代码注释。 -当编写纯粹的 Objective-C 代码时，我们基本遵守标准的 `Objective-C naming rules `_，这些命名规则可能与 C++ 风格指南中的大相径庭。例如，Google 的 C++ 风格指南中推荐使用下划线分隔的单词作为变量名，而(苹果的)风格指南则使用驼峰命名法，这在 Objective-C 社区中非常普遍。 +当编写纯粹的 Objective-C 代码时，我们基本遵守标准的 `Objective-C naming rules `_，这些命名规则可能与 C++ 风格指南中的大相径庭。例如，Google 的 C++ 风格指南中推荐使用下划线分隔的单词作为变量名，而(苹果的)风格指南则使用驼峰命名法，这在 Objective-C 社区中非常普遍。 -任何的类、类别、方法以及变量的名字中都使用全大写的 `首字母缩写 `_。这遵守了苹果的标准命名方式，如 URL、TIFF 以及 EXIF。 +任何的类、类别、方法以及变量的名字中都使用全大写的 `首字母缩写 `_。这遵守了苹果的标准命名方式，如 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 `_。 +方法名应尽量读起来就像句子，这表示你应该选择与方法名连在一起读起来通顺的参数名。（例如，``convertPoint:fromRect:`` 或 ``replaceCharactersInRange:withString:``）。详情参见 `Apple’s Guide to Naming Methods `_。 访问器方法应该与他们 ``要获取的`` 成员变量的名字一样，但不应该以get作为前缀。例如： diff --git a/google-python-styleguide/LICENSE b/google-python-styleguide/LICENSE index d645695..62589ed 100644 --- a/google-python-styleguide/LICENSE +++ b/google-python-styleguide/LICENSE @@ -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, diff --git a/google-python-styleguide/index.rst b/google-python-styleguide/index.rst index dfbccca..c465f90 100644 --- a/google-python-styleguide/index.rst +++ b/google-python-styleguide/index.rst @@ -16,14 +16,14 @@ :翻译: .. line-block:: - `guoqiao `_ v2.19 + `guoqiao `_ v2.19 `xuxinkun `_ v2.59 `captainfffsama `_ v2.6 `楼宇 `_ 2023 年 4 月 16 日更新 :项目主页: - `Google Style Guide (英文原版) `_ - - `Google 开源项目风格指南 - 中文版 `_ + - `Google 开源项目风格指南 - 中文版 `_ :协议: Python风格指南的源文件采用Apache License 2.0协议, 文本内容采用 `CC-BY 3.0 `_ 协议. diff --git a/google-python-styleguide/python_language_rules.rst b/google-python-styleguide/python_language_rules.rst index 2c34237..f23b3d3 100644 --- a/google-python-styleguide/python_language_rules.rst +++ b/google-python-styleguide/python_language_rules.rst @@ -524,7 +524,7 @@ Lambda函数 举个例子, 一个特性不能仅仅用于获取和设置一个内部属性: 因为不涉及计算, 没有必要用特性 (应该把该属性设为公有). 而用特性来限制属性的访问或者计算 **简单** 的衍生值则是正确的: 这种逻辑简单明了. - 应该用 ``@property`` `装饰器 (decorator) `_ 来创建特性. 自行实现的特性装饰器属于威力过大的功能. + 应该用 ``@property`` `装饰器 (decorator) `_ 来创建特性. 自行实现的特性装饰器属于威力过大的功能. 特性的继承机制难以理解. 不要用特性实现子类能覆写 (override) 或扩展的计算功能. @@ -607,7 +607,7 @@ True/False的求值 通常会产生更清晰、更优雅的代码. 尤其是让熟练使用Lisp和Scheme(还有Haskell, ML等)的程序员感到舒适. 缺点: - 可能引发让人困惑的bug, 例如下面这个依据 `PEP-0227 `_ 改编的例子: + 可能引发让人困惑的bug, 例如下面这个依据 `PEP-0227 `_ 改编的例子: .. code-block:: python diff --git a/google-python-styleguide/python_style_rules.rst b/google-python-styleguide/python_style_rules.rst index 3128a00..f251aae 100644 --- a/google-python-styleguide/python_style_rules.rst +++ b/google-python-styleguide/python_style_rules.rst @@ -24,7 +24,7 @@ Python风格规范 不要用反斜杠表示 `显式续行 (explicit line continuation) `_. -应该利用 Python 的 `圆括号, 中括号和花括号的隐式续行 (implicit line joining) `_ . 如有需要, 你可以在表达式外围添加一对括号. +应该利用 Python 的 `圆括号, 中括号和花括号的隐式续行 (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:`缩进 ` 章节的解释. @@ -242,9 +242,9 @@ Shebang行 -------------------- .. tip:: - 大部分 ``.py`` 文件不必以 ``#!`` 开始. 可以根据 `PEP-394 `_ , 在程序的主文件开头添加 ``#!/usr/bin/env python3`` (以支持 virtualenv) 或者 ``#!/usr/bin/python3``. + 大部分 ``.py`` 文件不必以 ``#!`` 开始. 可以根据 `PEP-394 `_ , 在程序的主文件开头添加 ``#!/usr/bin/env python3`` (以支持 virtualenv) 或者 ``#!/usr/bin/python3``. -(译者注: 在计算机科学中, `Shebang `_ (也称为Hashbang)是一个由井号和叹号构成的字符串行(#!), 其出现在文本文件的第一行的前两个字符. 在文件中存在Shebang的情况下, 类Unix操作系统的程序载入器会分析Shebang后的内容, 将这些内容作为解释器指令, 并调用该指令, 并将载有Shebang的文件路径作为该解释器的参数. 例如, 以指令#!/bin/sh开头的文件在执行时会实际调用/bin/sh程序.) +(译者注: 在计算机科学中, `Shebang `_ (也称为Hashbang)是一个由井号和叹号构成的字符串行(#!), 其出现在文本文件的第一行的前两个字符. 在文件中存在Shebang的情况下, 类Unix操作系统的程序载入器会分析Shebang后的内容, 将这些内容作为解释器指令, 并调用该指令, 并将载有Shebang的文件路径作为该解释器的参数. 例如, 以指令#!/bin/sh开头的文件在执行时会实际调用/bin/sh程序.) 内核会通过这行内容找到Python解释器, 但是Python解释器在导入模块时会忽略这行内容. 这行内容仅对需要直接运行的文件有效. @@ -258,7 +258,7 @@ Shebang行 **文档字符串** - Python 的文档字符串用于注释代码. 文档字符串是包、模块、类或函数里作为第一个语句的字符串. 可以用对象的 ``__doc__`` 成员自动提取这些字符串, 并为 ``pydoc`` 所用. (可以试试在你的模块上运行 ``pydoc`` 并观察结果). 文档字符串一定要用三重双引号 ``"""`` 的格式 (依据 `PEP-257 `_ ). 文档字符串应该是一行概述 (整行不超过 80 个字符), 以句号、问号或感叹号结尾. 如果要写更多注释 (推荐), 那么概述后面必须紧接着一个空行, 然后是剩下的内容, 缩进与文档字符串的第一行第一个引号对齐. 下面是更多有关文档字符串的格式规范. + Python 的文档字符串用于注释代码. 文档字符串是包、模块、类或函数里作为第一个语句的字符串. 可以用对象的 ``__doc__`` 成员自动提取这些字符串, 并为 ``pydoc`` 所用. (可以试试在你的模块上运行 ``pydoc`` 并观察结果). 文档字符串一定要用三重双引号 ``"""`` 的格式 (依据 `PEP-257 `_ ). 文档字符串应该是一行概述 (整行不超过 80 个字符), 以句号、问号或感叹号结尾. 如果要写更多注释 (推荐), 那么概述后面必须紧接着一个空行, 然后是剩下的内容, 缩进与文档字符串的第一行第一个引号对齐. 下面是更多有关文档字符串的格式规范. **模块** @@ -325,7 +325,7 @@ Shebang行 Returns: ("返回:") 生成器应该用 "Yields:" ("生成:" ) - 描述返回值的类型和意义. 如果函数仅仅返回 ``None``, 这一小节可以省略. 如果文档字符串以 Returns (返回) 或者 Yields (生成) 开头 (例如 ``"""返回 Bigtable 的行, 类型是字符串构成的元组."""``) 且这句话已经足以描述返回值, 也可以省略这一小节. 不要模仿 Numpy 风格的文档 (`例子 `_). 他们在文档中记录作为返回值的元组时, 写得就像返回值是多个值且每个值都有名字 (没有提到返回的是元组). 应该这样描述此类情况: "返回: 一个元组 (mat_a, mat_b), 其中 mat_a 是..., 且 ...". 文档字符串中使用的辅助名称不需要和函数体的内部变量名一致 (因为这些名称不是 API 的一部分). + 描述返回值的类型和意义. 如果函数仅仅返回 ``None``, 这一小节可以省略. 如果文档字符串以 Returns (返回) 或者 Yields (生成) 开头 (例如 ``"""返回 Bigtable 的行, 类型是字符串构成的元组."""``) 且这句话已经足以描述返回值, 也可以省略这一小节. 不要模仿 Numpy 风格的文档 (`例子 `_). 他们在文档中记录作为返回值的元组时, 写得就像返回值是多个值且每个值都有名字 (没有提到返回的是元组). 应该这样描述此类情况: "返回: 一个元组 (mat_a, mat_b), 其中 mat_a 是..., 且 ...". 文档字符串中使用的辅助名称不需要和函数体的内部变量名一致 (因为这些名称不是 API 的一部分). Raises: (抛出:) 列出与接口相关的所有异常和异常描述. 用类似 Args (参数) 小节的格式，写成异常名+冒号+空格/换行, 并添加悬挂缩进. 不要在文档中记录违反 API 的使用条件时会抛出的异常 (因为这会让违背 API 时出现的效果成为 API 的一部分, 这是矛盾的). @@ -453,7 +453,7 @@ Shebang行 **块注释和行注释** - 最后一种需要写注释的地方是代码中复杂的部分. 如果你可能在以后 `代码评审 (code review) `_ 时要解释某段代码, 那么现在就应该给这段代码加上注释. 应该在复杂的操作开始前写上若干行注释. 对于不是一目了然的代码, 应该在行尾添加注释. + 最后一种需要写注释的地方是代码中复杂的部分. 如果你可能在以后 `代码评审 (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 diff --git a/google-shell-styleguide/features_and_bugs.rst b/google-shell-styleguide/features_and_bugs.rst index 466c9d7..f9c6a83 100644 --- a/google-shell-styleguide/features_and_bugs.rst +++ b/google-shell-styleguide/features_and_bugs.rst @@ -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 diff --git a/google-shell-styleguide/index.rst b/google-shell-styleguide/index.rst index e892bcd..01eb10b 100644 --- a/google-shell-styleguide/index.rst +++ b/google-shell-styleguide/index.rst @@ -14,10 +14,10 @@ .. line-block:: - `Bean Zhang `_ v1.26 + `Bean Zhang `_ v1.26 :项目主页: - `Google Style Guide `_ - - `Google 开源项目风格指南 - 中文版 `_ + - `Google 开源项目风格指南 - 中文版 `_ diff --git a/google-typescript-styleguide/index.rst b/google-typescript-styleguide/index.rst new file mode 100644 index 0000000..d96d2d0 --- /dev/null +++ b/google-typescript-styleguide/index.rst @@ -0,0 +1,16 @@ +0. 扉页 +============ + +:原作者: + .. line-block:: + + 详细作者列表请参见英文原版的 Git 仓库. + +:翻译: + .. line-block:: + + - `Google 开源项目风格指南 - 中文版 `_ + +:项目主页: + + - `Google Style Guide `_ diff --git a/google-typescript-styleguide/source_organization.rst b/google-typescript-styleguide/source_organization.rst index 4edca29..992ed75 100644 --- a/google-typescript-styleguide/source_organization.rst +++ b/google-typescript-styleguide/source_organization.rst @@ -30,7 +30,7 @@ TypeScript 代码必须使用路径进行导入。这里的路径既可以是相 在 TypeScript 有两种组织代码的方式：命名空间（namespace）和模块（module）。 -不允许使用命名空间，在 TypeScript 中必须使用模块（即 `ES6 模块 `_ ）。也就是说，在引用其它文件中的代码时必须以 ``import {foo} from 'bar'`` 的形式进行导入和导出。 +不允许使用命名空间，在 TypeScript 中必须使用模块（即 `ES6 模块 `_ ）。也就是说，在引用其它文件中的代码时必须以 ``import {foo} from 'bar'`` 的形式进行导入和导出。 不允许使用 ``namespace Foo { ... }`` 的形式组织代码。命名空间只能在所用的外部第三方库有要求时才能使用。如果需要在语义上对代码划分命名空间，应当通过分成不同文件的方式实现。 diff --git a/google-typescript-styleguide/type_system.rst b/google-typescript-styleguide/type_system.rst index 369299f..fa11612 100644 --- a/google-typescript-styleguide/type_system.rst +++ b/google-typescript-styleguide/type_system.rst @@ -275,7 +275,7 @@ TypeScript 支持使用 `类型别名 `_ ，而 ES6 的新增类型能够更明确地表达程序员的设计思路。此外， ``Map`` 类型的键和 ``Set`` 类型的元素都允许使用 ``string`` 以外的其他类型。 +然而，相比使用上面的这种形式，在 TypeScript 中应当考虑使用 ES6 新增的 ``Map`` 与 ``Set`` 类型。因为 JavaScript 对象有一些 `令人困惑又不符合预期的行为 `_ ，而 ES6 的新增类型能够更明确地表达程序员的设计思路。此外， ``Map`` 类型的键和 ``Set`` 类型的元素都允许使用 ``string`` 以外的其他类型。 TypeScript 内建的 ``Record`` 允许使用已定义的一组键创建类型。它与关联数组的不同之处在于键是静态确定的。关于它的使用建议，参见 :ref:`ts-mapped-conditional-types` 一节。