Rubyでもプログラムの中にコメントを埋め込むことが可能です。とはいえRubyの文法を学んだ方の中で、コメントに何を書けば良いかを学んだ方は少ないかもしれません。コメントは、プログラムの中にメモを残せる機能ですが、何でも書いて良い訳ではありません。後から読む人に向けたメッセージと考えると良いかもしれません。
今回はRubyのコメントの記述方法と何を書き残せば良いかについて紹介します。
コメントとは？
Rubyに限らずほとんどのプログラム言語は、プログラムの実行に影響しないコメントを記述することが可能です。Rubyにおけるコメントの書き方を解説する前に、そもそもコメントとしてどんなことを書けば良いかについて紹介します。
プログラミング言語におけるコメントとは
プログラミング言語とは、コンピュータが実行する命令の組み合わせを人が読めるようにしたものです。そのため、プログラムにはコンピュータの動作に必要な内容が記載されています。しかし、なぜその命令の組み合わせが使われるかは、ソースコードに記述されていません。
そのため人がプログラムを読むためには、なぜその命令の組み合わせが必要だったかを知っていなければなりません。とはいえソースコードだけでそこまで理解するのは困難です。そこでソースコードに適切なメモが書かれていると、プログラムを理解しやすくなります。コメントとは、このようにソースコードを読む方を助けてくれる重要な情報です。
コメントに何を書けばいいのか
先ほど説明したように、なぜその命令の組み合わせが使われるかの理解を助けてくれる内容がコメントとして記述されていると、後からそのソースコードを修正する際に助かります。
例えばある特定の変数が使われる理由がコメントとして書かれていれで、後から仕様を見直す際に、なぜこの変数を使うことになったが理解できます。
なおよく変更履歴や処理内容がコメントとして書かれていることがありますが、変更履歴はバージョン管理の仕組みを利用すべきですし、処理内容はクラス名やメソッド名から解ることが多いので、必ずしもコメントとして記述する必要の無いケースもあります。
もちろん日本語でOK
オープンソースで公開されているプログラムのソースコードを見ると、必ずコメントが英語で書かれています。これは、開発に参加しているプログラマーが世界各地におり、英語を共通語にするとの取り決めがあるからです。同じように外国の方が開発に参加しているプロジェクトでは、英語でコメントを記述します。
とはいえRubyのプログラムのコメントを英語で書かなければならない、ということはありません。チームメンバーが全員日本人なら、日本語のコメントで十分です。
なお、Rubyをはじめとするほとんどのプログラム言語では、かなや漢字を含むコメントを記述できます。ただし、長い文章を書いてしまうと読み難くなるので、短く解りやすいコメントを心がけてください。
Rubyのコメントの書き方
プログラムにコメントを書く場合、行をまるごとコメントにするケースや、プログラム記述の右側にコメントを書くケースなどがあり、Rubyでもそのような書き方が可能です。次からRubyにおけるコメントの書き方を解説します。
#を使う
Rubyのプログラムにコメントを書く際によく使われるのが、#を使う方法です。Rubyでは、プログラムの中に#が記述されている場合、#からその行の改行までをコメントとして扱います。
例えば行の最初の文字が#なら、その行は全てコメントです。また、プログラム記述の右側に#を記述した場合は、#から改行までがコメントとして扱われます。
Rubyのコメントの例
# １行まるごとコメント str = "コメント" # 式の右側にコメントを記述
埋め込みドキュメントを使う
Rubyでは、「=begin」と「=end」で囲まれた複数の行をまとめてコメントにできます。これにより、ある程度長いドキュメントもプログラムの中に埋め込むことが可能です。
埋め込みドキュメントの例
=begin ここに書かれた内容は コメントとして 扱われます。 =end
長く使われているC言語の文法は今使わているプログラミング言語の文法に影響を与えています。C言語では「/*」と「*/」で囲むことで、複数の行をコメントにすることが可能です。Rubyのこの機能にあたるのが「=begin」と「=end」です
__END__を利用する
__END__はRubyのスクリプトの終わりを意味するキーワードです。もしこれ以降にプログラムが書かれていたとしても、読み込まれることはありません。そのため、これ以降をコメントとして扱えます。
さらにDATAオブジェクトを利用すれば、__END__以降に書かれた内容を読み取ることが可能なので、テストデータをコメントのように記述しておき、プログラムのデバックなどで利用することもできます。
__END__の記述例
__END__ ID,Name,Attr,Code 1001,Test,attr1,12345678 1002,Sample,attr2,23456789
１行目の#!はスクリプト実行用
もし、Rubyのソースファイルの1行目が下記のように記述してあれば、それはコメントではありません。このファイルをコマンドのように実行するための仕組みです。
Rubyスクリプトの1行目の例
#!/usr/bin/env ruby
LinuxやmacOSでは、chmodコマンドでテキストファイルに実行権を設定できます。ただし、実行権を設定しただけではシェルスクリプトとして実行されます。しかし、上記のように記述することでシェルスクリプトではなく、rubyスクリプトとして実行することが可能です。
Rubyのソースファイルをコマンドとして実行する例
$ cat test.rb #!/usr/bin/env ruby puts "Rubyで実行中" $ chmod +x test.rb $ ./test.rb Rubyで実行中 $
コメントの応用例
先ほど紹介したように、本来コメントとして書くべき内容とは、なぜその命令の組み合わせが使われるかの理解を助けてくれる内容です。しかしプログラム開発中にコメントを使ったテクニックを活用するケースがよくあります。次からそのようなコメントの応用例を紹介します。
自分に対するメモ
完成したプログラムに記述するべきコメントは、先ほど紹介したように、なぜその命令の組み合わせが使われるかの理解を助けてくれる内容です。
しかしコメントの使い方はそれだけではありません。まるでTODOのように、プログラムを書いている最中に気が付いて自分に対するメモをコメントとして書いておくことが可能です。
例えば、「後で〇〇の処理を追加する必要がある」や「後で読み易くする必要がある」などです。なお、このようなメモは後で消す必要があります。そのため、自分に対するメモのコメントは、他のメモと区別しやすいように工夫してください。
自分に対するメモのコメントの例
# TODO: この関数は読み易くすること
プログラムの一部を無効にする
使わなくなったプログラムの一部を残しておきたい場合、その処理をコメントにすることがソースコードに残すことが可能です。この機能は、プログラムの動作確認のためのコードを残す場合などに利用できます。
なおこのようなプログラムの一部をコメントで無効にすることを「コメントアウトする」と言います。Rubyの場合、1行のみコメントアウトする場合は#が使えますが、処理をまとめてコメントアウトする場合は、=beginと=endを使います。
コメントアウトの例
=begin def debug_v(v) puts "変数の値= " + v end =end str = "コメント" # debug_v(str) value = "値1" # debug_v(value) puts str + value
まとめ
これまで紹介したようにプログラムに記載するコメントには、なぜその命令の組み合わせが使われるかの理解を助けてくれる内容を記載しておくことで、後から機能追加等で編集する際に大きな助けになります。Rubyのプログラムを書いた場合も、#や=begin～=endなどを使って、解りやすいコメントを記述してください。
さらに自分用のメモやコメントアウトしてソースコードを残す方法としても有効です。ぜひRubyのプログラミングに活用しましょう。
Rubyはスクリプト言語の一種ですが、最初のスクリプト言語と言われるのはシェルスクリプトです。そのため多くのスクリプト言語がシェルスクリプトの文法の影響を受けています。そしてRubyの#を使ったコメントの書き方もシェルスクリプトから引き継いだ機能です。