Rubyスタイルガイドを読む: コメント、アノテーション、マジックコメント

こんにちは、hachi8833です。前回の命名編に続き、今回のコメント編も英語圏に寄った指示が多く見受けられます。 このセクションで興味深いのは、「コメントを増やすよりコードを改善せよ」というメッセージ自体が繰り返し主張されていることです。 こうした指示は、本来であればそれこそスタイルに1行書いて簡潔に終わらせたいところだと想像できますが、どれほど口を酸っぱくして指示しても、結局多くの人が残念なコメント記法を使ってしまっているということなのでしょう。 Rubyスタイルガイドを読む: 総もくじ 前回: Rubyスタイルガイドを読む: 命名 次回: Rubyスタイルガイドを読む: クラスとモジュール(1)構造 コメント(comment) 参照: bbatsov/ruby-style-guide よく書けたコードは、それ自体が最も優れたドキュメントになる。コメントを追加する前に、もう一度自問して欲しい: 「このコメントを足さなくてもいいようにコードを改良できないだろうか?」ひと手間かけてコードを改良してからドキュメントを書けば、単なるコメント追加よりずっと明確になるはずだ。 — Steve McConnell 4-01【統一】コード自身に語らせろ(コメントは最小限に) Write self-documenting code and ignore the rest of this section. Seriously! 「コメント編についてはこれさえやってくれれば、ここから先はもう読まなくたっていい(マジでマジで)」とあるぐらいなので、ダメなコメントがどれほど多いかを実感できますね。 追伸: ないと困るコメントについて 不要なコメントを削ることに夢中になるあまり、必要なコメントまで削ってしまわないようにしたいです。 以下のようなコメントはないと困るorあると喜ばれるコメントです。 ロジックだけではわからないコーディングの背景や理由(特に黒魔術系) 参考にしたURL(モンキーパッチなどを流用した場合など) 「ダメなコードを言い訳するコメント」でなければ、そのコメントはもしかすると必要かもしれません。 コードをクイズにしてしまわないための、読む人にやさしい的確なコメントを心がけたいと思います。 4-02【統一】コメントは英語(≒自国語)で書くこと Write comments in English. どよめきが聞こえてきそうな指示ですが、日本語圏であれば「自国語で書く」と理解してよいと思います(学校の教科である「国語」を米国ではEnglishと呼んでいるのと同じですね)。 以下いくつか英文法に寄った指示がありますが、日本語に合わないところは適宜解釈するとよいでしょう。 4-03【統一】コメント記号#とコメント記号の間は1スペース開けること Use one space between the leading # character of the comment and the text of the comment. これは美観上の理由で統一したと思います。私自身、#の後ろにスペースがないと窮屈な印象を受けます。 4-04【統一】1語より長いコメント文は冒頭を大文字にし、句読点を省略せず、ピリオドの後にスペースをひとつ置く Comments longer than a word are capitalized and use punctuation. Use one space after periods. 2語以上のコメントは文として扱うようにという指示です。 上の2つは、コーディングというよりも英文のスタイルの統一ですね。英文ドキュメントにも文法とは別にスタイルというものがあり、スタイルは出版社やコミュニティによって異なります。 「箇条書きの最後にピリオドを置くかどうか」「見出しの単語をすべて大文字にするかどうか」などは英文法ではなく、英語のスタイルの範疇です。文法とスタイルは分野を問わずごっちゃにされやすい傾向があります。 4-05【統一】無駄なコメントは削ぎ落とすこと Avoid superfluous comments. # 不可 counter += 1 # counterに1足す 学校の授業のコードサンプルでは説明のためにこういう冗長なコメントが大量に使われることがよくありますが、もしかすると英語圏ではそれを真に受けてずっとやり続けている人が割りといるのかもしれません。英語圏に限りませんが。 4-06【統一】コメントを古いままにしないこと Keep existing comments up-to-date. An outdated comment is worse than no comment at all. 「コメントを更新しないのは、コメントがないよりもずっとたちが悪い」とのことです。 4-07【統一】ダメなコードをカバーしようとするコメントを書くな Avoid writing comments to explain bad code. Refactor the code to make it self-explanatory. (“Do or do not—there is no try.” Yoda) これも「心がけ」の範疇ですね。抽象度の高いコードでは逆にコメントがないとクイズになってしまうかもしれません。 おまけ 「Do or do not—there is no try.」は、ヨーダ記法という用語の元にもなったヨーダの名言からの引用です。 この発音には東洋人訛りを意図的に混入させていると思われますが、私の聞き取り能力ではそこまで区別できません(´・ω・`)。「主人公を導く、途方もない力を持つ謎の老師」は東洋人へのステロタイプのひとつです。 アノテーション(annotation) ※当初の「注釈」を「アノテーション」に改めました。 いわゆるcommentとは別にannotationについて言及されています。 comment: 特定の大文字キーワードで始まっていないフリースタイル(本記事では「コメント」) annotation: 大文字のキーワードで始まり、commentよりも形式が定まっている(本記事では「アノテーション」) アノテーションの大文字キーワードはIDEやコード解析ツールでもサポートされていることがありますので、効果的に利用しましょう。 def bar # FIXME: ←「大文字キーワード+コロン+スペース」はコメント中でもハイライトされる(FIXME: ←冒頭以外でも有効) baz(:quux) end よく書けたコードは、うまいジョークと似ている: どちらも説明すればするほど野暮になる — Russ Olsenが伝えた、ある古参プログラマの金言 4-08【統一】アノテーションは、説明したいコードのすぐ上に書くこと Annotations should usually be written on the line immediately above the relevant … Continue reading Rubyスタイルガイドを読む: コメント、アノテーション、マジックコメント