Ruby multi-line comments

For over a year now, I’ve been working in Ruby on Rails (mostly for Fanpop and more recently for Cooking For Engineers) and one of the things that I wished I could do in Ruby was block comments. Internet searches I performed last year didn’t yield anything, so I gave up. Well, last week, I looked around again and found a solution.

Comments in ruby are handled by preceding the comment with a hash (#):

# This whole line is a comment
x = Array.new # tailing comment

But what happens if you want to comment more than one line at a time? In C, comments are always block comments: /* comment */ and can span multiple lines. In C++, you have both single line comments ( // a single line comment ) and block comments ( /* comment */ ), so why does Ruby have only single line comments?

When I last looked for multiple line comments in Ruby, I found a lot of websites and forums where the “solution” was to use an editor or IDE that lets you highlight multiple lines and insert (and remove) hashes from the beginning of each line with just a couple keystrokes. That’s fine, but what if you’re not using an editor that does that and you want to quickly comment out a couple blocks of code for testing purposes? I ended up resorting to the use of if false:

if false
code that I want to be ignored
...
last line that I want ignored
end

There are several problems with this technique of which two are most important:
1. The code between if false and end must be syntactically correct. That means if you have any comments, you have to comment it out with a hash and your code blocks must be properly nested and closed. If you don’t the parser won’t be able to properly figure out what to do with the code.
2. Initializing variables inside the block will actually result in those variables being initialized even if you expect the block to never be executed or interpreted. For example, if you have a hash with multiple value pairs set called params and then you have the following code, don’t be surprised if params is cleared:

if false
params = Hash.new
end

So you do you do comment blocks? Well, it turns out Ruby supports two types of comments - implementation comments (which use hashes, #) and documentation comments. Documentation comments start with =begin and end with =end. Typically, these two lines need to be at the beginning of the line (without leading spaces or tabs), but you’re mileage may vary.

=begin
code that is now commented out
...
doesn't matter what is in here...
could be gibberish or real code
=end

Magic. There is a problem with this: =begin and =end comments are supposed to be for documentation use (to generate documentation using a tool like rdtool). If you’re using the comments to quickly comment out a large block of code for testing or you don’t use embedded documentation, then =begin and =end could be very useful to you.