> 良好的代码是最佳的文档。当你要加一个注释时,扪心自问,“如何改善代码让它不需要注释?” 改善代码,再写相应文档使之更清楚。 > ——Steve McConnell * 编写让人一目了然的代码然后忽略这一节的其它部分。我是认真的! * 用英语写注释。 * `#` 与注释文字之间使用一个空格。 * 注释超过一个单词了,应句首大写并使用标点符号。句号后使用[一个空格](http://en.wikipedia.org/wiki/Sentence_spacing)。 * 避免肤浅的注释。 ~~~ # 差 counter += 1 # 计数器加一 ~~~ * 及时更新注释。过时的注解比没有注解还差。 > 好代码就像是好的笑话 - 它不需要解释  > ——Russ Olsen * 避免替烂代码写注释。重构代码让它们看起来一目了然。(要嘛就做,要嘛不做——不要只是试试看。——Yoda) ### [](https://github.com/JuanitoFatas/ruby-style-guide/blob/master/README-zhCN.md#注解)注解 * 注解应该直接写在相关代码那行之前。 * 注解关键字后面,跟着一个冒号及空格,接着是描述问题的文字。 * 如果需要用多行来描述问题,后续行要放在 `#` 号后面并缩排两个空格。 ~~~ def bar # FIXME: 这在 v3.2.1 版本之后会异常崩溃,或许与 # BarBazUtil 的版本更新有关 baz(:quux) end ~~~ * 在问题是显而易见的情况下,任何的文档会是多余的,注解应放在有问题的那行的最后,并且不需更多说明。这个用法应该是例外而不是规则。 ~~~ def bar sleep 100 # OPTIMIZE end ~~~ * 使用 `TODO` 标记以后应加入的特征与功能。 * 使用 `FIXME` 标记需要修复的代码。 * 使用 `OPTIMIZE` 标记可能影响性能的缓慢或效率低下的代码。 * 使用 `HACK` 标记代码异味,即那些应该被重构的可疑编码习惯。 * 使用 `REVIEW` 标记需要确认其编码意图是否正确的代码。举例来说:`REVIEW: 我们确定用户现在是这么做的吗?` * 如果你觉得恰当的话,可以使用其他定制的注解关键字,但别忘记录在项目的 `README` 或类似文档中。