注釋

良好的代碼是最佳的文檔。當你要加一個注釋時，捫心自問，“如何改善代碼讓它不需要注釋？” 改善代碼，再寫相應(yīng)文檔使之更清楚。
——Steve McConnell

• 編寫讓人一目了然的代碼然后忽略這一節(jié)的其它部分。我是認真的！
• 用英語寫注釋。
• # 與注釋文字之間使用一個空格。
• 注釋超過一個單詞了，應(yīng)句首大寫并使用標點符號。句號后使用一個空格。

• 避免膚淺的注釋。

  # 差
  counter += 1 # 計數(shù)器加一

• 及時更新注釋。過時的注解比沒有注解還差。

好代碼就像是好的笑話 - 它不需要解釋 
——Russ Olsen

• 避免替爛代碼寫注釋。重構(gòu)代碼讓它們看起來一目了然。（要嘛就做，要嘛不做——不要只是試試看。——Yoda）

注解

• 注解應(yīng)該直接寫在相關(guān)代碼那行之前。
• 注解關(guān)鍵字后面，跟著一個冒號及空格，接著是描述問題的文字。

• 如果需要用多行來描述問題，后續(xù)行要放在 # 號后面并縮排兩個空格。

  def bar
    # FIXME: 這在 v3.2.1 版本之后會異常崩潰，或許與
    #   BarBazUtil 的版本更新有關(guān)
    baz(:quux)
  end

• 在問題是顯而易見的情況下，任何的文檔會是多余的，注解應(yīng)放在有問題的那行的最后，并且不需更多說明。這個用法應(yīng)該是例外而不是規(guī)則。

  def bar
    sleep 100 # OPTIMIZE
  end

• 使用 TODO 標記以后應(yīng)加入的特征與功能。

• 使用 FIXME 標記需要修復(fù)的代碼。
• 使用 OPTIMIZE 標記可能影響性能的緩慢或效率低下的代碼。
• 使用 HACK 標記代碼異味，即那些應(yīng)該被重構(gòu)的可疑編碼習慣。
• 使用 REVIEW 標記需要確認其編碼意圖是否正確的代碼。舉例來說：REVIEW: 我們確定用戶現(xiàn)在是這么做的嗎？
• 如果你覺得恰當?shù)脑?，可以使用其他定制的注解關(guān)鍵字，但別忘記錄在項目的 README 或類似文檔中。