編寫Ruby代碼注釋時(shí)需要注意的一些問題

    寫出自解釋文檔代碼，然后讓這部分歇息吧。這不是說著玩。
    使用英文編寫注釋。
    使用一個(gè)空格將注釋與符號隔開。
    注釋超過一個(gè)單詞了，應(yīng)句首大寫并使用標(biāo)點(diǎn)符號。句號后使用 一個(gè)空格

    避免多余的注釋。

  # bad
  counter += 1 # increments counter by one

    隨時(shí)更新注釋，沒有注釋比過期的注釋更好。

    不要為糟糕的代碼寫注釋。重構(gòu)它們，使它們能夠“自解釋”。(Do or do not - there is no try.)

    注解應(yīng)該寫在緊接相關(guān)代碼的上方。
    注解關(guān)鍵字后跟一個(gè)冒號和空格，然后是描述問題的記錄。

    如果需要多行來描述問題，隨后的行需要在 # 后面縮進(jìn)兩個(gè)空格。

  def bar
   # FIXME: This has crashed occasionally since v3.2.1. It may
   # be related to the BarBazUtil upgrade.
   baz(:quux)
  end

    如果問題相當(dāng)明顯，那么任何文檔就多余了，注解也可以（違規(guī)的）在行尾而沒有任何備注。這種用法不應(yīng)當(dāng)在一般情況下使用，也不應(yīng)該是一個(gè) rule。

  def bar
   sleep 100 # OPTIMIZE
  end

    使用 TODO 來備注缺失的特性或者在以后添加的功能。

    使用 FIXME 來備注有問題需要修復(fù)的代碼。

    使用 OPTIMIZE 來備注慢的或者低效的可能引起性能問題的代碼。

    使用 HACK 來備注那些使用問題代碼的地方可能需要重構(gòu)。

    使用 REVIEW 來備注那些需要反復(fù)查看確認(rèn)工作正常的代碼。例如： REVIEW: 你確定客戶端是怎樣正確的完成 X 的嗎？

    使用其他自定義的關(guān)鍵字如果認(rèn)為它是合適的，但是確保在你的項(xiàng)目的 README 或者類似的地方注明。