Rubyでコメントを使用する方法

前書き

コメントは、コンパイラーおよびインタープリターによって無視されるコンピュータープログラムの行です。 コメントを使用して、プログラムの各部分が何をしているのかについて、より多くのコンテキストまたは説明を提供することにより、他のプログラマーがプログラムを理解しやすくすることができます。 さらに、コメントを使用して特定のソリューションを選択した理由を説明したり、プログラムの問題のある部分や不完全な部分が修正中に一時的に実行されるのを防ぐこともできます。

コンテキストを説明するコメントなど、一部のコメントはコードに永久に残る場合がありますが、プログラムの作成中に残したメモなど、一時的なコメントもあります。

Rubyプログラムでコメントを使用してメモを残す方法、およびコメントをデバッグツールとして使用する方法を見てみましょう。

Rubyのコメントはハッシュマーク( )で始まり、次のように行末まで続きます。

# This is a comment in Ruby

必須ではありませんが、コメントの読みやすさを向上させるために、ハッシュマークの後に空白スペースを配置する必要があります。

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

チュートリアルhttps://www.digitalocean.com/community/tutorials/how-to-write-your-first-ruby-program [最初のRubyプログラムの書き方]のような単純なRubyプログラムでは、コメントを使用して、コードの各部分で何が起こっているかについての詳細を追加できます。

greetings.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リストとして表示するプログラムでは、次のようなコメントが表示される場合があります。これにより、コードの機能についてもう少し説明できます。

sharks.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>"

まだ `+ map `や ` join `のようなものに慣れていないかもしれませんが、コメントはこのプログラムがどのように動作し、出力がどのように見えるかを示しています。 やってみよう。 このコードを「 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>

インタプリタがコメントを無視したため、コメントが表示されないことに注意してください。 しかし、出力はおそらくあなたが期待していたものと一致したでしょう。 コメントは、特にコメントを読んでいる人がその言語を初めて使用する場合に、優れたコミュニケーションツールです。

コメントは、コメントするコードと同じインデントで行う必要があります。 つまり、インデントのないクラス定義にはインデントのないコメントがあり、それに続く各インデントレベルにはコメントしているコードに合わせたコメントがあります。

たとえば、https://en.wikipedia.org/wiki/Magic_8-Ball [Magic 8-Ball]ゲームのRuby実装です。 コンピューターは、あなたが尋ねる質問にランダムに答えます。 コメントは、各セクションのコードと同じレベルのインデントでインデントされていることに注意してください。

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

コメントは、元のプログラマであろうと、プロジェクトで使用または共同作業しているプログラマであろうと、プログラマを支援することになっています。 つまり、コメントはコードと同様に維持する必要があります。 コードと矛盾するコメントは、まったくコメントがないよりも悪いです。

始めたばかりのときは、自分が何をしているかを理解するのに役立つコメントをたくさん書くことができます。 しかし、より多くの経験を積むにつれて、_what_や_how_ではなく、コードの背後にある_why_を説明するコメントを使用する必要があります。 コードが特に扱いにくい場合を除き、コードを見ると、一般的にコードが何をしているか、またはどのようにそれを行っているかを知ることができます。

たとえば、Rubyを知ったら、この種のコメントはあまり役に立ちません。

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

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

場合によっては、もう少し詳細なコメントを書く必要があります。 それがブロックコメントの目的です。

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

ブロックコメントでは、各行はハッシュマークで始まり、読みやすいように1つのスペースが続きます。 複数の段落を使用する必要がある場合は、単一のハッシュマークを含む行で区切る必要があります。

Sinatra Webフレームワークのソースコードからのブロックコメントの例を次に示します。 この特定のコードがどのように機能するかについて、他の開発者にコンテキストを提供します。

...
 # 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には複数行コメント用の代替構文がありますが、めったに使用されません。 例を示しましょう。

multiline.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ボールゲームでは、コードが答えを正しく評価することを確認したいだけなので、ゲームが再び実行されないようにすることができます。 ゲームを再び開始するコード行をコメントアウトするだけです。

8ball.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で配列を操作するときに、いくつかの異なるアプローチを試してみることができます。 コメントを使用して各アプローチをテストし、どのアプローチが最も好きかを判断できます。

sharks.rb

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

# for shark in sharks do
#  puts shark
# end

sharks.each do |shark|
 puts shark
end

コードをコメントアウトすると、さまざまなプログラミング方法を試すことができ、プログラムの一部を体系的にコメントアウトして実行することにより、エラーの原因を見つけるのに役立ちます。

結論

Rubyプログラム内でコメントを使用すると、将来の自分を含め、プログラムが人間にとって読みやすくなります。 関連性があり有用な適切なコメントを含めると、他の人がプログラミングプロジェクトであなたと協力しやすくなります。 また、長期にわたってプロジェクトを再訪するときに、将来作成したコードを理解するのにも役立ちます。