編寫Ruby代碼注釋時需要注意的一些問題_ruby專題

    寫出自解釋文檔代碼，然後讓這部分歇息吧。這不是說著玩。
    使用英文編寫注釋。
    使用一個空格將注釋與符號隔開。
    注釋超過一個單詞了，應句首大寫並使用標點符號。句號後使用 一個空格

    避免多餘的注釋。

  # bad  counter += 1 # increments counter by one

    隨時更新注釋，沒有注釋比到期的注釋更好。

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

    註解應該寫在緊接相關代碼的上方。
    註解關鍵字後跟一個冒號和空格，然後是描述問題的記錄。

    如果需要多行來描述問題，隨後的行需要在 # 後面縮排兩個空格。

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

    如果問題相當明顯，那麼任何文檔就多餘了，註解也可以（違規的）在行尾而沒有任何備忘。這種用法不應當在一般情況下使用，也不應該是一個 rule。

  def bar   sleep 100 # OPTIMIZE  end

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

    使用 FIXME 來備忘有問題需要修複的代碼。

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

    使用 HACK 來備忘那些使用問題代碼的地方可能需要重構。

    使用 REVIEW 來備忘那些需要反覆查看確認工作正常的代碼。例如： REVIEW: 你確定用戶端是怎樣正確的完成 X 的嗎？

    使用其他自訂的關鍵字如果認為它是合適的，但是確保在你的項目的 README 或者類似的地方註明。