Commenting Ruby Code
| Previous | Table of Contents | Next |
| Simple Ruby Examples | Understanding Ruby Variables |
<
| Purchase and download the full PDF and ePub editions of this Ruby eBook for only $8.99
|
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
<google>BUY_RUBY_ESSENTIALS_BOTTOM</google>
| Previous | Table of Contents | Next |
| Simple Ruby Examples | Understanding Ruby Variables |
