Difference between revisions of "Commenting Ruby Code"

Latest revision as of 20:03, 27 October 2016

Commenting code is a little like going to the dentist. We don't really want to have to do it but deep down we know it is a good thing to do. No matter how well written and self-explanatory your Ruby script it is still good practice to add comments. There a number of reasons for doing this. Firstly, it is possible that someone else may one day have to modify or fix bugs in your code. Good comments will help those who are new to your code to understand what it does. Secondly, no matter how well you understand your Ruby scripts now, I can assure you that in 6 months time you will look at the code and wonder how it all fits together (trust me, I've been programming for a long time and sometimes return to something I developed years ago and cannot believe I even wrote it!).

Comments are also useful for blocking out lines of code that you no longer wish to run (typically something that is done when trying to debug problems in complex programs).

What exactly is Commenting

Commenting is the process of marking content in a program such that it is ignored by the Ruby interpreter. This is typically used so that the programmer can write notes alongside the code describing what that code does such that other humans who look at the code will have a better chance of understanding the code.

Comments can span multiple lines, occupy a single line, or be tacked onto the end of a line of code.

Single Line Ruby Comments

Single line comments in a Ruby script are defined with the '#' character. For example, to add a single line comment to a simple script:

# This is a comment line - it explains that the next line of code displays a welcome message
print "Welcome to Ruby!"

Comments lines can be grouped together:

# This is a comment line
# it explains that the next line of code displays 
# a welcome message

Although a better way to implement multi-line comments is to use the comment begin and end markers as described later in this chapter.

Comments on Lines of Code

It is common practice to place comments on the same line as the associated code to which the comment applies. For example, if we wanted to place a comment on the same line as our print statement we would do so by placing the comment after a '#' marker:

print "Welcome to Ruby!"     # prints the welcome message

Note that everything on the line after the '#' is ignored by the Ruby interpreter. You cannot, therefore, put more code after the '#' and expect it to be executed. Additional code must be placed on the next line.

Multi Line or Block Ruby Comments

Multiple lines of text or code can be defined as comments using the Ruby =begin and =end comment markers. These are known as the comment block markers.

For example, to provide a comment block containing multiple lines of descriptive text:

=begin
This is a comment line
it explains that the next line of code displays 
a welcome message
=end

Similarly, lines of Ruby code can be blocked out so that they are not executed by the interpreter using the block markers:

=begin
print "Welcome to Ruby Essentials!"
print "Everything you need to know about Ruby"
=end