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

投稿日: 2019-11-08 2022-10-08
タグ: Development, Ruby

序章

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

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

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

コメントの構文と使用法

Rubyのコメントはハッシュマークで始まります（#）そして次のように行の終わりまで続けます：

# This is a comment in Ruby

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

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

チュートリアル最初の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>

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

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

たとえば、これは Magic8-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

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

始めたばかりのときは、自分がしていることを理解するのに役立つコメントをたくさん書くことができます。しかし、経験を積むにつれて、何またはどのようにではなく、コードの背後にある理由を説明するためにコメントを使用することを検討する必要があります。コードが特にトリッキーでない限り、コードを見ると、通常、コードが何を実行しているか、またはどのように実行しているかがわかります。

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

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

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

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

コメントをブロックする

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

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

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

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

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

The =begin と =end 行は行の先頭にある必要があります。インデントすることはできません。これが使用されることはめったに見られないのはこのためです。

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

インラインコメント

インラインコメントは、コード自体に続くステートメントの同じ行にあります。他のコメントと同様に、それらはハッシュマークで始まり、読みやすくするために1つの空白文字が続きます。

通常、インラインコメントは次のようになります。

[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.

並んでいるコメントは、必要な場合、およびプログラムを読んでいる人に役立つガイダンスを提供できる場合にのみ使用する必要があります。

テスト用のコードのコメントアウト

コードを文書化する方法としてコメントを使用することに加えて、ハッシュマークを使用して、現在作成しているプログラムのテストまたはデバッグ中に実行したくないコードをコメントアウトすることができます。場合によっては、新しいコード行を追加した後にエラーが発生したときに、それらのいくつかをコメントアウトして、除去のプロセスを通じて問題をトラブルシューティングできるかどうかを確認することができます。

たとえば、Magic 8-Ballゲームでは、コードが答えを正しく評価することを確認することに関心があるため、ゲームが再度実行されないようにする必要があります。ゲームを再開するコード行をコメントアウトするだけです。

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プログラム内でコメントを使用すると、将来の自分自身を含め、人間がプログラムを読みやすくすることができます。関連性があり有用な適切なコメントを含めると、他の人がプログラミングプロジェクトであなたと協力しやすくなります。また、長期間後にプロジェクトを再検討するときに、将来作成したコードを理解するのにも役立ちます。

getdocs

13036