TOC

Verwendung von Kommentaren in Ruby

Einführung

Kommentare sind Zeilen in Computerprogrammen, die von Compilern und Interpreten ignoriert werden. Mithilfe von Kommentaren können Sie anderen Programmierern das Verständnis Ihrer Programme erleichtern, indem Sie mehr Kontext oder Erläuterungen zu den einzelnen Programmteilen bereitstellen. Außerdem können Sie mithilfe von Kommentaren erläutern, warum Sie eine bestimmte Lösung ausgewählt haben, oder sogar verhindern, dass ein problematischer oder unvollständiger Teil Ihres Programms vorübergehend ausgeführt wird, während Sie einen Fix ausarbeiten.

Einige Kommentare bleiben möglicherweise für immer im Code, z. B. diejenigen, die den Kontext erläutern, während andere Kommentare temporär sein können, z. B. Notizen, die Sie beim Erstellen Ihres Programms hinterlassen.

Sehen wir uns an, wie Sie Kommentare in Ruby-Programmen verwenden, um Notizen zu hinterlassen, und wie Sie sie als Debugging-Tool verwenden.

Kommentare in Ruby beginnen mit einem Rautezeichen (+ # +) und werden wie folgt bis zum Ende der Zeile fortgesetzt:

# This is a comment in Ruby

Obwohl dies nicht erforderlich ist, sollten Sie nach der Raute ein Leerzeichen einfügen, um die Lesbarkeit des Kommentars zu verbessern.

Wenn Sie ein Programm ausführen, werden im Code keine Hinweise auf Kommentare angezeigt. Der Ruby-Interpreter ignoriert sie vollständig. Kommentare sind im Quellcode für Menschen zum Lesen, nicht für Computer zum Ausführen.

In einem einfachen Ruby-Programm, wie dem im Tutorial https://www.digitalocean.com/community/tutorials/how-to-write-your-first-ruby-pragramsHow to Write Your First Ruby Program], schreiben Sie Ihr erstes Ruby-Programm Mit Kommentaren können Sie zusätzliche Details zu den einzelnen Codeteilen anzeigen:

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!"

Diese Kommentare geben Ihnen eine allgemeine Vorstellung davon, was die einzelnen Programmabschnitte tun und wie sie funktionieren.

In einem Programm, das über ein Array iteriert und dessen Inhalt als HTML-Liste anzeigt, werden möglicherweise Kommentare wie diese angezeigt, die etwas mehr Erläuterungen zur Funktionsweise des Codes enthalten:

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

Sie sind vielleicht noch nicht mit Dingen wie "+ map " und " join " vertraut, aber die Kommentare geben Ihnen eine Vorstellung davon, wie dieses Programm funktionieren sollte und wie die Ausgabe aussehen könnte. Versuch es. Platzieren Sie diesen Code in einer Datei mit dem Namen " sharks.rb +" und führen Sie ihn aus:

ruby sharks.rb

Sie sehen die Programmausgabe:

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

Beachten Sie, dass Sie die Kommentare nicht sehen, da der Interpreter sie ignoriert hat. Aber die Ausgabe entsprach wahrscheinlich Ihren Erwartungen. Kommentare sind ein großartiges Kommunikationsinstrument, insbesondere wenn die Person, die die Kommentare liest, für die Sprache neu ist.

Kommentare sollten im selben Einzug wie der Code erfolgen, den sie kommentieren. Das heißt, eine Klassendefinition ohne Einrückung hätte einen Kommentar ohne Einrückung, und jede folgende Einrückungsebene hätte Kommentare, die mit dem Code, den sie kommentiert, ausgerichtet sind.

Hier ist zum Beispiel eine Ruby-Implementierung eines Magic 8-Ball -Spiels. Der Computer gibt eine zufällige Antwort auf eine von Ihnen gestellte Frage. Beachten Sie, dass die Kommentare auf derselben Einrückungsebene wie der Code in den einzelnen Abschnitten eingerückt werden.

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

Kommentare sollen Programmierern helfen, egal ob es sich um den ursprünglichen Programmierer handelt oder um jemanden, der das Projekt verwendet oder daran mitarbeitet. Dies bedeutet, dass die Kommentare genau wie der Code gepflegt werden müssen. Ein Kommentar, der dem Code widerspricht, ist schlimmer als gar kein Kommentar.

Wenn Sie gerade erst anfangen, können Sie viele Kommentare verfassen, um zu verstehen, was Sie tun. Wenn Sie jedoch mehr Erfahrung sammeln, sollten Sie Kommentare verwenden, um das Warum hinter dem Code und nicht das Was oder Wie zu erläutern. Wenn der Code nicht besonders knifflig ist, kann ein Blick auf den Code im Allgemeinen Aufschluss darüber geben, was der Code tut oder wie er es tut.

Diese Art von Kommentar ist beispielsweise nicht hilfreich, wenn Sie Ruby kennen:

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

Dieser Kommentar wiederholt, was der Code bereits tut, und obwohl er die Programmausgabe nicht beeinflusst, ist er beim Lesen von Code besonders laut.

Manchmal müssen Sie Kommentare verfassen, die etwas detaillierter sind. Dafür sind Blockkommentare gedacht.

Sie können Blockkommentare verwenden, um komplizierteren Code oder Code zu erklären, mit dem der Leser nicht vertraut sein dürfte. Diese längeren Kommentare gelten für einige oder den gesamten folgenden Code und werden auf derselben Ebene wie der Code eingerückt.

In Blockkommentaren beginnt jede Zeile mit der Raute gefolgt von einem einzelnen Leerzeichen zur besseren Lesbarkeit. Wenn Sie mehr als einen Absatz verwenden müssen, sollten diese durch eine Linie getrennt sein, die eine einzelne Raute enthält.

Hier ist ein Beispiel für einen Blockkommentar aus dem Quellcode des Sinatra Web-Frameworks. Es bietet anderen Entwicklern einen Kontext zur Funktionsweise dieses speziellen Codes:

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

Blockkommentare eignen sich hervorragend, wenn Sie Codeteile gründlich erläutern müssen. Sie sollten jedoch versuchen, eine Überkommentierung des Codes zu vermeiden, da diese Kommentare redundant sein und zusätzliches Rauschen verursachen können. Vertrauen Sie darauf, dass andere Programmierer Ruby-Code verstehen, es sei denn, Sie schreiben für eine bestimmte Zielgruppe. Kommentare sollten Kontext hinzufügen, nicht den Code duplizieren.

Ruby hat eine alternative Syntax für mehrzeilige Kommentare, wird jedoch selten verwendet. Hier ist ein Beispiel:

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

Die Zeilen "+ = begin" und "+ = end" müssen am Zeilenanfang stehen. Sie können nicht eingerückt werden. Aus diesem Grund wird dies nur selten verwendet.

Schauen wir uns als nächstes die Inline-Kommentare an.

Inline-Kommentare werden in derselben Zeile einer Anweisung nach dem Code selbst angezeigt. Wie andere Kommentare beginnen sie mit einem Rautezeichen, gefolgt von einem einzelnen Leerzeichen zur besseren Lesbarkeit.

Inline-Kommentare sehen im Allgemeinen so aus:

[code]  # Inline comment about the code

Inline-Kommentare sollten sparsam verwendet werden, können jedoch zur Erklärung kniffliger oder nicht offensichtlicher Codeteile hilfreich sein. Sie können auch nützlich sein, wenn Sie der Meinung sind, dass Sie sich möglicherweise nicht mehr an eine Codezeile erinnern, die Sie in Zukunft schreiben, oder wenn Sie mit jemandem zusammenarbeiten, von dem Sie wissen, dass er nicht mit allen Aspekten des Codes vertraut ist.

Wenn Sie beispielsweise in Ihren Ruby-Programmen nicht viel Mathematik verwenden, wissen Sie oder Ihre Mitarbeiter möglicherweise nicht, dass Folgendes eine komplexe Zahl erstellt. Daher möchten Sie möglicherweise einen Inline-Kommentar dazu einfügen:

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

Sie können auch Inline-Kommentare verwenden, um den Grund für eine Aktion zu erläutern:

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

Kommentare, die in der Zeile gemacht werden, sollten nur verwendet werden, wenn dies erforderlich ist und wenn sie dem Leser des Programms hilfreiche Hinweise geben können.

Zusätzlich zur Verwendung von Kommentaren als Möglichkeit, Code zu dokumentieren, können Sie mit der Raute-Markierung Code auskommentieren, den Sie nicht ausführen möchten, während Sie ein Programm testen oder debuggen, das Sie gerade erstellen. Wenn nach dem Hinzufügen neuer Codezeilen Fehler auftreten, möchten Sie möglicherweise einige davon auskommentieren, um festzustellen, ob Sie das Problem durch die Behebung beheben können.

Zum Beispiel möchten Sie im Magic 8-Ball-Spiel möglicherweise verhindern, dass das Spiel erneut ausgeführt wird, weil Sie nur sicherstellen möchten, dass der Code die Antwort richtig auswertet. Sie können einfach die Codezeile auskommentieren, die das Spiel erneut startet:

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

In Kommentaren können Sie auch Alternativen ausprobieren, während Sie festlegen, wie eine Lösung in Ihrem Code implementiert werden soll. Sie können beispielsweise verschiedene Ansätze ausprobieren, wenn Sie mit Arrays in Ruby arbeiten. Sie können Kommentare verwenden, um jeden Ansatz zu testen und festzustellen, welcher Ihnen am besten gefällt:

sharks.rb

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

# for shark in sharks do
#  puts shark
# end

sharks.each do |shark|
 puts shark
end

Durch das Auskommentieren von Code können Sie verschiedene Programmiermethoden ausprobieren und die Fehlerquelle ermitteln, indem Sie Teile eines Programms systematisch auskommentieren und ausführen.

Fazit

Die Verwendung von Kommentaren in Ihren Ruby-Programmen kann die Lesbarkeit von Programmen für den Menschen verbessern, einschließlich Ihres zukünftigen Selbst. Das Einfügen geeigneter Kommentare, die relevant und nützlich sind, erleichtert es anderen, bei der Programmierung von Projekten mit Ihnen zusammenzuarbeiten. Sie helfen Ihnen auch dabei, den Code zu verstehen, den Sie in Zukunft geschrieben haben, wenn Sie Ihr Projekt nach einer langen Zeit erneut aufrufen.

Related