TOC

Comment utiliser les commentaires en Ruby

introduction

Les commentaires sont des lignes de programmes informatiques qui sont ignorées par les compilateurs et les interprètes. Vous pouvez utiliser les commentaires pour rendre vos programmes plus faciles à comprendre pour les autres programmeurs en les utilisant pour fournir plus de contexte ou d’explications sur ce que fait chaque partie d’un programme. En outre, vous pouvez utiliser des commentaires pour expliquer pourquoi vous avez choisi une solution particulière, voire empêcher une partie problématique ou incomplète de votre programme de s’exécuter temporairement pendant que vous élaborez un correctif.

Certains commentaires peuvent rester dans le code pour toujours, tels que ceux qui expliquent le contexte, alors que d’autres peuvent être temporaires, tels que les notes que vous laissez vous-même pendant la construction de votre programme.

Voyons comment utiliser les commentaires dans les programmes Ruby pour laisser des notes, ainsi que comment les utiliser comme outil de débogage.

Les commentaires en Ruby commencent par un signe dièse (+ # +) et continuent jusqu’à la fin de la ligne, comme ceci:

# This is a comment in Ruby

Bien que cela ne soit pas nécessaire, vous devez insérer un espace après le signe dièse pour améliorer la lisibilité du commentaire.

Lorsque vous exécutez un programme, vous ne voyez aucune indication de commentaire dans le code; l’interprète Ruby les ignore complètement. Les commentaires sont dans le code source pour les humains à lire, pas pour les ordinateurs à exécuter.

Dans un programme Ruby simple, comme celui du tutoriel Comment rédiger votre premier programme Ruby, vous pouvez utiliser les commentaires pour donner des détails supplémentaires sur ce qui se passe dans chaque partie du code:

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

Ces commentaires vous donnent une idée générale de ce que fait chaque section du programme et de son fonctionnement.

Dans un programme qui itère sur un tableau et affiche son contenu sous forme de liste HTML, vous pouvez voir des commentaires comme celui-ci, qui donnent un peu plus d’explications sur le rôle du code:

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

Vous ne connaissez peut-être pas encore les fonctions + map + et + join +, mais les commentaires vous donnent une idée du fonctionnement de ce programme et de son apparence. Essaye le. Placez ce code dans un fichier nommé + sharks.rb + et exécutez-le:

ruby sharks.rb

Vous verrez la sortie du programme:

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

Notez que vous ne voyez pas les commentaires, car l’interprète les a ignorés. Mais le résultat correspond probablement à ce que vous attendiez. Les commentaires sont un excellent outil de communication, surtout lorsque la personne qui lit les commentaires est nouvelle dans la langue.

Les commentaires doivent être faits avec le même retrait que le code qu’ils commentent. Autrement dit, une définition de classe sans indentation aurait un commentaire sans indentation et chaque niveau d’indentation suivant aurait des commentaires alignés sur le code qu’elle commente.

Par exemple, voici une implémentation Ruby d’un jeu Magic 8-Ball. L’ordinateur donnera une réponse aléatoire à une question que vous posez. Notez que les commentaires sont indentés au même niveau d’indentation que le code de chaque section.

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

Les commentaires sont supposés aider les programmeurs, que ce soit le programmeur d’origine ou une autre personne utilisant ou collaborant dans le projet. Cela signifie que les commentaires doivent être conservés exactement comme le code. Un commentaire qui contredit le code est pire que pas de commentaire du tout.

Lorsque vous débutez, vous pouvez écrire de nombreux commentaires pour vous aider à comprendre ce que vous faites. Mais au fur et à mesure que vous gagnerez en expérience, vous devriez envisager d’utiliser des commentaires pour expliquer le pourquoi du code, par opposition au _ what_ ou au how. À moins que le code ne soit particulièrement délicat, le regarder peut généralement indiquer ce que fait le code ou comment il le fait.

Par exemple, ce genre de commentaire ne vous est pas utile une fois que vous connaissez Ruby:

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

Ce commentaire réitère ce que le code fait déjà. Bien que cela n’affecte pas la sortie du programme, il s’agit d’un bruit supplémentaire lorsque vous lisez du code.

Parfois, vous devrez écrire des commentaires un peu plus détaillés. C’est à cela que servent les commentaires de bloc.

Vous pouvez utiliser des commentaires de blocage pour expliquer un code plus complexe ou un code que le lecteur ne devrait pas connaître. Ces commentaires plus longs s’appliquent à tout ou partie du code qui suit et sont également mis en retrait au même niveau que le code.

Dans les commentaires de bloc, chaque ligne commence par le signe dièse suivi d’un espace unique pour la lisibilité. Si vous devez utiliser plusieurs paragraphes, ils doivent être séparés par une ligne contenant un seul signe de hachage.

Voici un exemple de commentaire de bloc du code source du Sinatra Web Framework. Cela fournit un contexte aux autres développeurs sur le fonctionnement de ce code particulier:

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

Les commentaires de bloc sont parfaits lorsque vous devez expliquer en détail des morceaux de code. Cependant, évitez de trop commenter votre code, car ces commentaires pourraient être redondants et créer du bruit supplémentaire. Faites confiance aux autres programmeurs pour comprendre le code Ruby, sauf si vous écrivez pour un public particulier. Les commentaires doivent ajouter un contexte, ne pas dupliquer le code.

Ruby a une syntaxe alternative pour les commentaires multilignes, mais il est rarement utilisé. Voici un exemple:

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

Les lignes + = begin et` + = end` doivent être au début de la ligne. Ils ne peuvent pas être mis en retrait. C’est pour cette raison que vous verrez rarement cela utilisé.

Regardons les commentaires en ligne ensuite.

Les commentaires en ligne apparaissent sur la même ligne d’une instruction, à la suite du code lui-même. Comme d’autres commentaires, ils commencent par un signe dièse, suivi d’un seul caractère d’espacement pour la lisibilité.

Généralement, les commentaires en ligne ressemblent à ceci:

[code]  # Inline comment about the code

Les commentaires en ligne doivent être utilisés avec parcimonie, mais ils peuvent être efficaces pour expliquer des parties de code difficiles ou non évidentes. Ils peuvent également être utiles si vous pensez ne pas vous souvenir d’une ligne du code que vous écrivez à l’avenir ou si vous collaborez avec une personne que vous connaissez ne connaissez peut-être pas tous les aspects du code.

Par exemple, si vous n’utilisez pas beaucoup de mathématiques dans vos programmes Ruby, vous ou vos collaborateurs pouvez ne pas savoir que ce qui suit crée un nombre complexe. Vous souhaiterez donc peut-être inclure un commentaire en ligne à ce sujet:

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

Vous pouvez également utiliser des commentaires en ligne pour expliquer la raison pour laquelle vous faites quelque chose:

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

Les commentaires en ligne ne doivent être utilisés que lorsque cela est nécessaire et qu’ils peuvent fournir des indications utiles à la personne qui lit le programme.

En plus d’utiliser les commentaires pour documenter le code, vous pouvez utiliser le signe dièse pour mettre en commentaire le code que vous ne souhaitez pas exécuter pendant que vous testez ou déboguez un programme que vous êtes en train de créer. Parfois, lorsque vous rencontrez des erreurs après avoir ajouté de nouvelles lignes de code, vous pouvez en commenter quelques-unes pour voir si vous pouvez résoudre le problème tout au long du processus d’élimination.

Par exemple, dans le jeu Magic 8-Ball, vous souhaitez peut-être empêcher le jeu de fonctionner à nouveau parce que vous souhaitez simplement vous assurer que le code évalue la réponse correctement. Vous pouvez simplement commenter la ligne de code qui redémarre le jeu:

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

Les commentaires vous permettent également d’essayer des alternatives pendant que vous déterminez comment implémenter une solution dans votre code. Par exemple, vous pouvez essayer différentes approches lorsque vous travaillez avec des tableaux dans Ruby. Vous pouvez utiliser des commentaires pour tester chaque approche et déterminer celle que vous préférez:

requins.rb

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

# for shark in sharks do
#  puts shark
# end

sharks.each do |shark|
 puts shark
end

La mise en commentaire du code vous permet d’essayer différentes méthodes de programmation et vous aide également à trouver la source d’une erreur en commentant et en exécutant systématiquement des parties d’un programme.

Conclusion

L’utilisation de commentaires dans vos programmes Ruby peut rendre les programmes plus lisibles par les humains, y compris par votre avenir. L’inclusion de commentaires appropriés, pertinents et utiles, facilite la collaboration avec d’autres personnes sur des projets de programmation. Ils vous aideront également à comprendre le code que vous avez écrit à l’avenir lorsque vous revisitez votre projet après une longue période.

Related