Orthogonal Thought | Random musings from the creator of Cooking For Engineers and Lead Architect of Fanpop

AUTHORS

CATEGORIES

ARCHIVE

Ruby multi-line comments

Posted 22 May, 2007 at 12:05am by Michael Chu
(Filed under: Ruby on Rails, Web 2.0)

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

10 comments to Ruby multi-line comments

Chris, December 31st, 2007 at 2:36 pm:

  • I am a returning programmer, but the Ruby book I bought still (assumed) that I would read between the lines as I over embellish "Hello Matz".

    I learn best by digging as deep as possible and take the "hello world" to a new level. All this being said, I was disappointed that my book failed to mention this small point of the block comment must not have any leading spaces or tabs as stated clearly (here, "Typically, these two lines need to be at the beginning of the line (without leading spaces or tabs),…".

    Thank you Orthogonal Thought, et al.

    Chris…

Jonah Dempcy, June 5th, 2008 at 5:49 pm:

  • I can't believe this is the only option! Are there are any plans for Ruby to support multi-line comments?

    Conversely, I wish CSS would support single-line comments for the same reason. In CSS, I often want to comment out large blocks of code but cannot, because it's full of comments which will cause my intended comment to end prematurely. It isn't fair! Such a simple, basic feature should be a requirement for any modern programming language. Is there any reason not to support both single- and multi-line commenting?

Michael Chu, June 6th, 2008 at 11:43 am:

  • Yeah, kind of ridiculous isn't it? Many editors that understand Ruby will insert hashes (#) in front of each line of a block that you highlight and mark for commenting, but I like to use text editors and not IDE's for programming…

Russell Ianniello, February 19th, 2009 at 8:17 pm:

  • "but you’re mileage may vary."

    your

Michael Chu, February 19th, 2009 at 11:40 pm:

  • Fixed the "you're" -> "your" typo.

Peter Kappus, August 10th, 2010 at 8:11 am:

  • Don't forget you can do this: (a perl relic, I believe)

    =begin
    Between =begin and =end, any number
    of lines may be written. All of these
    lines are ignored by the Ruby interpreter.
    =end

    Thanks to Michael Morin @ About.com
    http://ruby.about.com/od/rubyfeatures/a/comment.htm

Michael Chu, August 10th, 2010 at 10:55 am:

  • Isn't the whole =begin =end construct what this post was about?

Matthias Lüttgert, December 30th, 2010 at 2:42 am:

  • <<EOC
    This is my comment and
    any stuff goes here.
    To stop the comment, EOC has to be at the outset of the line!
    EOC

    EOC may be replaced by EOF or any literal.

Ruby multi-line comment out – Richard Choi, April 4th, 2011 at 2:32 am:

Laszlo, September 27th, 2011 at 7:21 am:

  • ->Mathias
    Your solution has a drawback. The multi-line strings work similarly to the double quotes.
    So If the commented out code contains one or more of these:
    #{_code_}
    then Ruby will still try to execute the _code_ blocks and if the variables are not defined within those _code_ blocks then you get an error message.

NAVIGATION

SEARCH