> 良好的代码是最佳的文档。当你要加一个注释时，扪心自问，“如何改善代码让它不需要注释？” 改善代码，再写相应文档使之更清楚。 > ——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` 或类似文档中。