Method Comment

メソッドに関するコメントを書く場合は、メソッドの中ではなくメソッドの先頭にコメントを書きましょう。また、コードから明白に読み取れない重要な情報のみ伝えるようにしましょう。

メソッド定義の中で書かれるコメントというのは、コードの補助的な記述です。Rubyのコードなら、補助的な記述抜きで大局的な情報をも伝えることが可能です。メソッドの定義の中にコメントを書く必要がありそうだと感じたら、その前にまず、変数名やメソッド名、引数名や処理の分割などで、その情報をコードで明示的に表現出来ないかを考えましょう。
また、もしコードから明白に読み取れない重要な情報が存在する場合は、メソッドの先頭にコメントするようにしましょう。それによって、コードの中にコメントを埋もれさせるよりは、読み手に情報が伝わる可能性を高くすることが出来ます。
Rubyコーディング規約のコメントに関する規約も参照しましょう。