> 良好的代碼是最佳的文檔。當你要加一個注釋時，捫心自問，“如何改善代碼讓它不需要注釋？” 改善代碼，再寫相應文檔使之更清楚。
> ——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`?或類似文檔中。
