—[Google C++ 风格指南][google-c++]

这一部分的指南从 Google
[C++][google-c++-comments] 和 [Python][google-python-comments] 风格指南那边借鉴了很多。

每个类的定义都应该带些注释， 说明它是干什么的, 以及怎么用它。

如果文件里没有任何 class， 或者多于一个 class， 顶部应该有注释说明里面是什么。

  1. # 
  2. #  This list is made with
  3. #  lib/tasks/list_american_to_british_spelling_variants.rake.
  4. # 
  5. #  It contains words with general spelling variation patterns:
  6. #    [trave]led/lled, [real]ize/ise, [flav]or/our, [cent]er/re, plus
  7. #  and these extras:
  8. #    learned/learnt, practices/practises, airplane/aeroplane, ...
  10. sectarianizes: sectarianises
  11. neutralization: neutralisation

函数注释 (Function comments)

函数声明的前面都应该有注释，描述函数是做什么的，以及怎么用。
这些注释应该是 描述性的(descriptive) 比如 (“Opens the file”)
而不是 命令式的(imperative) 比如 (“Open the file”)；
注释描述这个函数，而不是告诉这个函数应该做什么。
总的来说，函数前面的注释并不负责解释函数是怎么做到它提供的功能的。
解释功能怎么实现的注释，应该零散的分布在函数内部的注释里。

每个函数都应该提到输入和输出是什么，除非碰到以下情况：

  • 非常短 (very short)
  • 很明显 (obvious)

你喜欢什么格式都行。在 Ruby 里两种常见的格式是 和 YARD。
你也可以直接简洁明了的写出来，比如这样：

这个部分有点小麻烦. 如果你下次 code review 需要解释这些代码的话， 你现在就应该写注释。
复杂的操作应该把注释写在前面。
单行的不太容易理解的代码, 注释应该写在代码后面。 

  1. def fallbacks_for(the_locale, opts = {})
  2.   #  dup() to produce an array that we can mutate.
  3.   ret = @fallbacks[the_locale].dup
  5.   #  We make two assumptions here:
  6.   #  1) There is only one default locale (that is, it has no less-specific
  7.   #     children).
  8.   #  2) The default locale is just a language. (Like :en, and not :"en-US".)
  9.   if opts[:exclude_default] &&
  10.       ret.last == default_locale &&
  12.   end
  14.   ret
  15. end

在另一方面，永远不要在注释里描述代码。你要假设读代码的人对这门语言的了解比你知道的多。

标点符号, 拼写和语法 (Punctuation, spelling, and grammar)

要注意注释里的标点符号, 拼写和语法；
注释写得好读起来也容易。

注释应该和叙述文 (narrative text) 一样易读 (readable)，
有着正确的大小写和标点符号。 在很多情况下。 完整的句子比句子碎片容易读得多。
短的注释， 比如跟在代码后面的， 可以不那么正式， 但风格应该一致。

虽然在提交代码时, 别人指出你在应该用分号的地方用了逗号, 这种小事蛮折磨人的.
但重要的是源代码应该保持高度的清晰和可读. 正确的标点符号, 拼写, 和语法非常重要.

当代码是临时解决方案，够用但是并不完美时，用 TODO 注释。

TODO 应该全大写, 然后是写这个注释的人名, 用圆括号括起来, 冒号可写可不写。
然后后面是解释需要做什么，统一 TODO 注释样式的目的是方便搜索。
括号里的人名不代表这个人负责解决这个问题, 只是说这个人知道这里要解决什么问题.
每次你写 TODO 注释的时候加上你的名字。 

  1.   #  错误
  2.   #  TODO(RS): Use proper namespacing for this constant.
  4.   #  错误
  5.   #  TODO(drumm3rz4lyfe): Use proper namespacing for this constant.
  7.   #  正确

注释掉的代码 (Commented-out code)

  • 注释掉的代码就不要留在代码库里了。
    [link]