- こちらの記事をきっかけに Ruby のコメントの書き方の方針について学びをまとめました
- 原文ソースはこちら → https://github.com/fortissimo1997/ruby-style-guide/blob/japanese/README.ja.md#%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88
根底にあるスタンス
良く書けたコードは、それ自身が最良のドキュメントでもある。 コメントを書こうとしている時は、常に自問してほしい、 "このコメントが不要になるようにコードを改善できるだろうか？" コードを改善した上で、ドキュメントでさらに明快にするのだ。
-- Steve McConnell
- この点は『ソースコード == ドキュメント』という Ruby 作者の主張並びに Ruby の言語特徴を汲んでいる
- コードが明快な分かりやすい記述であれば「コードを見れば分かる」という事
- 記事の作者は補足的に「実装の背景や理由などコードでは説明がつかない部分はコメントで補足説明が必要としている
コメントを書くなら読みやすく無駄を省き最適化する
悪いコードを説明するコメントは避けましょう。
自己説明的なコードへのリファクタリングを行いましょう
- 「読みやすい言語でコメントを残す（日本なら日本語）」「コメント記号(#)とコメント本文はスペース一個分空ける」などコメントを書くにしろ見やすい工夫は必須だと訴えている
注釈
- "コメント" とは別に "注釈 (アノテーション)" も手法としてある
- 以下引用の注釈を利用した例
def bar
# FIXME: 以前から挙動がおかしい
baz(:quux)
end
マジックコメント
-
マジックコメント... スクリプトエンコーディングを明示的に指定する際に使用。エディタでのエンコーディングを独自に指定したり、外部のスクリプトで使う設定を書く際にも使用- シェルスクリプトの一行目に書くおまじないと同じ
- 以下一例、Ruby 1.9 では、この記述がない場合のデフォルトエンコーディングは US-ASCII であるので、非ASCIIコードがあるのにこの記述がなかった場合はエラーになる
# -*- coding: UTF-8 -*-
p "abc".encoding
# => #<Encoding:UTF-8>
p "あいうえお".encoding
# => #<Encoding:UTF-8>
- マジックコメントは処理に関係する意味を持つ重要なコメントなので「一行に複数のマジックコメントを書かないようにする」「マジックコメント直下は一行分の空白行を空ける」
所感
- 個人的にはコメントは書けるなら書いた方が良いと考えていましたが、"コードが良ければ"コメントは不要という考え方もあるのかなと思った
- これは Ruby という言語に限った話かもしれませんが
- ただこの辺は会社によるという結論なのかなと思ったり
- RDoc を利用すれば Ruby のスタンスには反するような気もするので
- とある知り合いが「メソッド名も直観的なものが多いイメージ」と仰っていて、そういう意味で『コード = ドキュメント』と主張しているのかもしれないなと思った
参考資料・参考サイト