注釋

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

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

• 避免膚淺的注釋。

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

• 及時(shí)更新注釋。過(guò)時(shí)的注解比沒有注解還差。

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

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

注解

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

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

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

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

  def bar
    sleep 100 # OPTIMIZE
  end

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

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