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