Rubyのコードコメントを書く際に気をつけるべき事項

    説明不要のドキュメントコードを書いて、その部分を休ませる。これは単なるジョークではありません。
    英語を使ってコメントを書く。
    コメントと記号の間はスペースで区切ってください。
    コメントが1語以上の場合は、文頭に大文字と句読点をつけてください。ピリオドの後はスペースを使用する

    冗長なコメントは避けてください。

  # bad
  counter += 1 # increments counter by one

    コメントはいつでも更新可能です。期限切れのコメントほど良いものはありません。

    悪いコードにはコメントを書かない。説明不要になるようにリファクタリングしてください。(Do or do not - tryはありません。)

    アノテーションは、該当するコードのすぐ上に記述してください。
    注釈キーワードの後にコロンとスペースが続き、その後に問題を説明するレコードが続きます。

    問題を記述するために複数行が必要な場合、それ以降の行は#の後に空白2つ分インデントする必要があります。

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

    問題がかなり明白であれば、どんな文書も冗長であり、コメントは（不愉快なことに）何も言わずに行末にあることも可能です。この使い方は一般に使われるべきではありませんし、ルールとすべきでもありません。

  def bar
   sleep 100 # OPTIMIZE
  end

    TODOを使用して、不足している機能や後で追加される機能を記録します。

    FIXMEは、修正すべき問題があるコードを記録するために使用します。

    OPTIMIZEは、パフォーマンスの問題を引き起こす可能性のある遅いコードや非効率なコードを記録するために使用します。

    HACKを使用して、問題のあるコードを使用している箇所をリファクタリングする必要があるかもしれないことに注意してください。

    REVIEWは、正しく動作していることを確認するために繰り返し見る必要があるコードを記録するために使用します。例えば REVIEW: クライアントがどのようにXを正しく実行しているか、確認しましたか？

    適切と思われる場合は、他のカスタムキーワードを使用してください。ただし、プロジェクトのREADMEなどに必ず記述してください。