View source for Commenting Ruby Code

<table border="0" cellspacing="0" width="100%">
<tr>
<td width="20%">[[Simple Ruby Examples|Previous]]<td align="center">[[Ruby Essentials|Table of Contents]]<td width="20%" align="right">[[Understanding Ruby Variables|Next]]</td>
<tr>
<td width="20%">Simple Ruby Examples<td align="center"><td width="20%" align="right">Understanding Ruby Variables</td>
</table>
<hr>


<htmlet>ruby</htmlet>


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:

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

Comments lines can be grouped together:

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

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:

<pre>
print "Welcome to Ruby!"     # prints the welcome message
</pre>

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:

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

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

<pre>
=begin
print "Welcome to Ruby Essentials!"
print "Everything you need to know about Ruby"
=end
</pre>


<htmlet>ruby</htmlet>



<htmlet>ezoicbottom</htmlet>
<hr>
<table border="0" cellspacing="0" width="100%">
<tr>
<td width="20%">[[Simple Ruby Examples|Previous]]<td align="center">[[Ruby Essentials|Table of Contents]]<td width="20%" align="right">[[Understanding Ruby Variables|Next]]</td>
<tr>
<td width="20%">Simple Ruby Examples<td align="center"><td width="20%" align="right">Understanding Ruby Variables</td>
</table>