Rubyではコメントの使い方はどのようになりますか

2年 ago

3 minutes

はじめに

コンピュータプログラム内のコメントは、コンパイラやインタプリタによって無視される行です。他のプログラマがプログラムの各部分が何をしているのかをより理解しやすくするために、コメントを使ってさらなる文脈や説明を提供することができます。さらに、特定の解決策を選んだ理由を説明したり、問題のある部分や未完成な部分を一時的に実行しないようにするためにも、コメントを使用することができます。

いくつかのコメントは永遠にコードの中に残る可能性があります。例えば、文脈を説明するコメントなどです。一方で、自分のプログラムを構築する際に自分自身に残すメモなど、一時的なコメントもあります。

Rubyプログラム内でコメントを使用してメモを残す方法や、デバッグツールとしての使用方法について見てみましょう。

コメントの文法と使い方

ルビーのコメントはハッシュマーク(#)で始まり、その行の終わりまで続きます。

# This is a comment in Ruby

ハッシュマークの後に空白を入れることは必ずしも要求されていませんが、コメントの読みやすさを向上させるためにそうした方が良いでしょう。

プログラムを実行すると、コード内にコメントの表示はありません。Rubyのインタープリターはコメントを完全に無視します。コメントはコンピュータが実行するためではなく、人間が読むためのソースコードにあります。

Rubyのプログラミングチュートリアル「最初のRubyプログラムを作成する方法」のような簡単なRubyプログラムでは、コードの各部分で何が起こっているかについての追加の詳細をコメントとして記述することができます。

こんにちは.rb

# Display a prompt to the user
puts "Please enter your name."

# Save the input they type and remove the last character (the enter keypress)
name = gets.chop

# Print the output to the screen
puts "Hi, #{name}! I'm Ruby!"

これらのコメントには、プログラムの各セクションが何を行い、どのように機能するかの一般的なアイデアが示されています。

配列を反復処理し、その内容をHTMLリストとして表示するプログラムでは、以下のようなコメントが見られることがあります。これらのコメントは、コードの動作について少し詳しく説明しています。

サメ.rb

sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']

# transform each entry in the array to an HTML entity, with leading spaces and a newline.
listitems = sharks.map{ |shark| " <li>#{shark}</li>\n"}

# Print the opening <ul>, then print the array of list items
print "<ul>\n#{listitems.join}</ul>"

まだマップやジョインなどに慣れていないかもしれませんが、コメントを通じて、このプログラムの動作方法や出力の見た目についてのアイデアを掴むことができます。ぜひ試してみてください。このコードをsharks.rbという名前のファイルに配置して実行してください。

ruby sharks.rb

プログラムの出力が表示されます。

Output

<ul> <li>hammerhead</li> <li>great white</li> <li>dogfish</li> <li>frilled</li> <li>bullhead</li> <li>requiem</li> </ul>

通訳者が無視したため、コメントは表示されません。しかし、おそらく予想通りの結果が出力されたでしょう。特に言語に慣れていない方がコメントを読むことは、コミュニケーションの助けとなります。

コメントは、コードと同じインデントで行うべきです。つまり、インデントがないクラス定義にはインデントのないコメントがあるべきであり、それに続く各インデントレベルには、コメントがコードに対して揃って配置されるべきです。

例えば、以下はマジック8ボールゲームのRubyによる実装例です。コンピューターはあなたが尋ねる質問にランダムな答えを返します。各セクションのコメントは、コードと同じレベルのインデントで記述されていることに注目してください。

マジック8ボールのスクリプト（magic8ball.rb）を日本語で言い換える。

# The Eightball class represents the Magic 8-Ball.
class Eightball

# Set up the available choices
def initialize
@choices = ["Yes", "No", "All signs point to yes", "Ask again later", "Don't bet on it"]
end

# Select a random choice from the available choices
def shake
@choices.sample
end
end

def play
puts "Ask the Magic 8 Ball your question."

# Since we don't need their answer, we won't capture it.
gets

# Create a new instance of the Magic 8 Ball and use it to get an answer.
eightball = Eightball.new
answer = eightball.shake
puts answer

# Prompt to restart the game and evaluate the answer.
puts "Want to try again? Press 'y' to continue or any other key to quit."
answer = gets.chop

if answer == 'y'
play
else
exit
end
end

# Start the first game.
play

プログラマーに対して、コメントは原作者であるか、プロジェクトの利用または共同作業に参加している他の人に役立つものであるとされています。つまり、コメントもコードと同様にメンテナンスされなければなりません。コードと矛盾するコメントは、コメントを一切書かないよりも悪いです。

最初の段階では、自分のやっていることを理解するために、多くのコメントを書くかもしれません。しかし、経験を積んでいくと、コードの「なぜ」を説明するためにコメントを活用することを考えるべきです。コードが特に複雑でない限り、コードを見るだけで何をしているか、どのようにしているかは一般的にわかります。

例えば、Rubyを知っているとこのようなコメントはあまり役立ちません。

# print "Hello Horld" to the screen.
print "Hello World"

このコメントは、コードが既に行っていることを繰り返していますが、プログラムの出力には影響を与えません。ただし、コードを読む際には余分なノイズです。

時には、もう少し詳細なコメントを書く必要があることもあります。それがブロックコメントの用途です。

コメントをブロック

ブロックコメントを使用して、より複雑なコードや読者が馴染みがないと予想されるコードを説明することができます。これらの長いコメントは、その後のコードの一部またはすべてに適用され、コードと同じレベルでインデントされます。

ブロックコメントでは、各行はハッシュマークで始まり、可読性のためにその後にスペースが1つあります。複数の段落を使用する必要がある場合、それらは単一のハッシュマークを含む行で区切るべきです。

以下は、Sinatraウェブフレームワークのソースコードからのブロックコメントの例です。この特定のコードの動作について、他の開発者にいくつかの文脈を提供しています。

以下の文を日本語で自然に言い換えます。オプションは1つだけです。「https://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb」

...
# Some Rack handlers (Thin, Rainbows!) implement an extended body object protocol, however,
# some middleware (namely Rack::Lint) will break it by not mirroring the methods in question.
# This middleware will detect an extended body object and will make sure it reaches the
# handler directly. We do this here, so our middleware and middleware set up by the app will
# still be able to run.
class ExtendedRack < Struct.new(:app)
def call(env)
result, callback = app.call(env), env['async.callback']
return result unless callback and async?(*result)
after_response { callback.call result }
setup_close(env, *result)
throw :async
end
...

ブロックコメントは、コードの断片を詳しく説明する必要がある場合に非常に便利です。ただし、コードに過剰なコメントを付けすぎるのは避けるべきです。それらのコメントは冗長で追加のノイズを作り出す可能性があります。特定の対象読者向けに書いていない限り、他のプログラマにはRubyコードを理解する能力を信頼してください。コメントはコンテキストを追加するものであり、コードを重複させるものではありません。

Rubyには複数行コメントのための別の構文がありますが、あまり使われません。以下に例を示します：

以下は、複数行の.rbファイルです。

=begin
This is a multi-line comment.
You can use this approach to make your comments
span multiple lines without placing hash marks at the start of each
line.
=end

=beginと=endの行は行の先頭に配置しなければなりません。インデントされてはいけません。この理由から、これを使用することはほとんどありません。

次はインラインコメントについて見てみましょう。

インラインコメント

インラインコメントは、ステートメントの同じ行に現れ、そのコードの後に続きます。他のコメントと同様に、可読性のためにハッシュマークで始まり、その後に単一の空白文字が続きます。

一般的に、インラインコメントはこのように見える。

[code] # Inline comment about the code

インラインコメントは控えめに使用すべきですが、コードの難しい部分や一目ではわかりにくい部分を説明するのに効果的です。また、将来自分が書いたコードの行を覚えていないかもしれない場合や、コードのすべての側面に詳しくない人と協力している場合にも役立ちます。

例えば、Rubyのプログラムであまり数学を使用しない場合、あなたや共同作業者は次のような複素数を作成していることを知らないかもしれません。そのため、それに関するインラインコメントを含めることがあるかもしれません。

a=Complex(4,3) # Create the complex number 4+3i

何かをする理由を説明するために、インラインコメントを使うこともできます。

pi = 3.14159 # Intentionally limiting the value of pi for this program.

プログラムを読む人に役立つ指示を提供する場合のみ、コメントは必要な時に使用してください。

テスト用にコードをコメントアウトする

コードを記録するための方法としてコメントを使用するだけでなく、テストやデバッグ中に実行したくないコードをコメントアウトするためにハッシュマークを使用することもできます。新しいコードの行を追加した後にエラーが発生した場合、問題を特定するためにいくつかの行をコメントアウトしてみることで問題をトラブルシューティングすることができます。

例えば、マジック8ボールのゲームで、おそらくゲームを再度実行させたくない理由は、コードが正しく回答を評価するかどうかに興味があるからかもしれません。その場合、ゲームを再度開始するコードの行をコメントアウトするだけで良いです。

８ボール.rbを日本語で言い換えると「エイトボール.rb」となります。

...

# Prompt to restart the game and evaluate the answer.
puts "Want to try again? Press 'y' to continue or any other key to quit."
answer = gets.chop

if answer == 'y'
# play
else
exit
end
end
...

コメントは、コードにソリューションを実装する方法を決定する際に、代替方法を試すこともできます。例えば、Rubyで配列を扱う際には、いくつかの異なるアプローチを試したいかもしれません。コメントを使用して、それぞれのアプローチをテストし、最も好きな方法を決定することができます。

サメの.rb

sharks = ["Tiger", "Great White", "Hammerhead"]

# for shark in sharks do
# puts shark
# end

sharks.each do |shark|
puts shark
end

コードのコメントアウトによって、違ったプログラミング手法を試すことができるだけでなく、プログラムの一部をコメントアウトし、システム的に実行することでエラーの原因を特定することができます。

結論

Rubyプログラム内でコメントを使用すると、プログラムが人間にとって読みやすくなります。適切かつ有益なコメントを含めることで、他の人とのプログラミングプロジェクトでの共同作業が容易になります。また、長期的な期間が経過した後にプロジェクトを再訪した際に、自分が書いたコードを理解するのにも役立ちます。