Multi-Line Comments in Ruby?

Question

How can I comment multiple lines in Ruby?

Spatiotemporal

It's rather unfortunate that multiline comments in ruby look very much like a block of code. And given the high points awarded to this question (and the accepted answer) the people working on the ruby syntax should clearly think a bit about it. – Brucite

Answer 1

#!/usr/bin/env ruby

=begin
Every body mentioned this way
to have multiline comments.

The =begin and =end must be at the beginning of the line or
it will be a syntax error.
=end

puts "Hello world!"

<<-DOC
Also, you could create a docstring.
which...
DOC

puts "Hello world!"

"..is kinda ugly and creates
a String instance, but I know one guy
with a Smalltalk background, who
does this."

puts "Hello world!"

##
# most
# people
# do
# this


__END__

But all forgot there is another option.
Only at the end of a file, of course.

• This is how it looks (via screenshot) - otherwise it's hard to interpret how the above comments will look. Click to Zoom-in:

Dubiety

I really prefer using # over them all, mostly because it visually separates the commented lines better than =begin/=end or using the here-to method. And, nice job. – Radiance

For me, in Ruby 1.9.3p194, using the heredoc style as shown above gives as warning: possibly useless use of a literal in void context. – Fair

It's interesting that this answer makes some flaws in the syntax highlighter obvious. – Fiesta

Don't forget that =begin and =end cannot be preceded by any whitespace. – Leigha

And It is not possible to use =begin =end within a method – Pilcher

If you're reading Ruby code in an editor that highlights rdoc comments correctly, they stand out, and your comments are less cluttered with a "#" starting every line. What's not to like? OTOH, a scan through the std library shows two hits, and a small smattering amongst my gems. OTOH, almost all Perl code uses POD. Maybe because the tools for generating HTML and man pages from Perl POD comments are so much further along than Ruby's. – Splint

I would prefer to use #, but most of the time I use =begin ... =end because I'm too lazy to type all those # or learn how to do block comments in vim – Dermott

It's important to note that in the above example code, only the first =begin...=end and last block using # are picked up by rdoc when generating documentation. – Radiance

the Heredoc format <<-DOC will interpolate so you can't use #{} variables inside easily. and if you try to use <<-'DOC' (which basically tells heredoc not to perform interpolation), it will most likely screw your syntax highlighting. – Kazukokb

<<-DOC will also create a String instance. So best to stick to # or =begin. – Befool

@AlbertCatalà: And It is not possible to use =begin =end within a method I tested, and it seems to work within a method. However, you can't indent it. What did you have in mind when you said "not possible?" Do you mean that it doesn't work with rdoc or something? – Abvolt

@BenCrowell that is correct AlbertCatala is wrong. begin end block comments can be used anywhere. the only restriction is that they cannot contain any superceding whitespace on =begin or =end so they are very ugly unless at the root of a file – Akene

Answer 2

=begin
My 
multiline
comment
here
=end

Literalminded

Sure, you could do this. It works. This is incredibly rare. I find it ugly. Maybe I'm stuck in my ways? – Fair

I've found that if I include a tab before =begin or =end, the comments don't work. The =begin and =end each need to be written at the beginning of each line. – Disgusting

you're not alone @DavidJames. I've personally opted to have them all commented out by my editor. CMD+/ or ALT+/ is the convention for most. – Ungracious

@DavidJames, what would you do instead? Type a # and space before every single line? It's a lot of keystrokes especially if I start adding line breaks. – Koval

Answer 3

Despite the existence of =begin and =end, the normal and a more correct way to comment is to use #'s on each line. If you read the source of any ruby library, you will see that this is the way multi-line comments are done in almost all cases.

Putout

You might get arguments about the "more correct" part of your statement as they're both valid. I prefer using # because it's more obvious. When commenting out code it's important to make it obvious that's what happened. If you're viewing the code without the benefit of code coloring in an editor using =begin/=end can make it tough to figure out why code is being ignored. – Radiance

Sure, there are many "valid" ways to write comments. Let's be practical here. If you actually write Ruby and read what others write, you should be using # comments. (I am mystified why this had two downvotes. I guess the Stack Overflow community has to get it wrong sometimes!) – Fair

3 == three where def three; 1 + 1 + 1 end. Therefore both are valid. Who cares? Use 3! – Fair

@theTinMan While true, generally the only time you'd lack syntax highlighting (in my experience) is when you're using vi on a production server. In which case, you probably shouldn't be doing your development there, anyway. – Isidraisidro

@DavidJames Your example is ridiculous because it's more verbose. Putting a hash on every line is more verbose for longer comments. And if anyone thinks the phrase "/dev/urandom was used here for the nonblocking cryptographically-sound PRNG. Do not touch this code- it is magic" is my attempt at writing ruby, I would contend their confusion arises more from ignorance on their part than lack of clarity on mine. Which isn't to say your point is always invalid- it's just only a good one when commenting out code. But if your comment is just... comment... it should be clear either way. – Isidraisidro

@ParthianShot, even on my production hosts I have my standard ~/.vim defined. And some of my production hosts are for development by the users. – Radiance

@theTinMan I am experiencing a mixture of confused, hungry and tired. One of those emotions is a response to your comment. The default highlighting in vim usually works well. When don't you have highlighting? EDIT: It was confused. Took me a bit but I got it sussed. – Isidraisidro

You don't get default highlighting with a stripped vim on a ssh session with a terminal mismatch, or where vim doesn't understand the file type, especially on our hosts which are way out of date. My first task on any machine I help manage is to update vim from source to the latest full version just because I can't stand stripped vim but some machines I use I don't manage. – Radiance

This isn't actually an answer to his question, hence the downvotes. – Confiscable

Answer 4

#!/usr/bin/env ruby

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

puts "Hello world!"

Quibbling

+1 because I had no idea nesting was a thing in Ruby multiline comments. – Isidraisidro

@ParthianShot - It is not a thing - =begin and =end are ignored if not at the beginning of a line. Nesting does not seem to be possible. – Ducat

Nesting a comment inside a comment would result in either a single comment or a syntax error from trying to end a comment where there is no comment to end. /*I am a\n#nested\ncomment, which really serves no purpose*/ /*I am bound /*to*/ FAIL!*/ It could make sense if you have single line comments and code inside of a multiline comment, such as a function with documentation that you don't want people to use, but you also don't want to remove it from the file. – Thrashing

Answer 5

Using either:

=begin
This
is
a
comment
block
=end

or

# This
# is
# a
# comment
# block

are the only two currently supported by rdoc, which is a good reason to use only these I think.

Radiance

Another good reason to stick to =begin or # is that both <<-DOC and " syntaxes will generate useless string literals at execution. – Befool

Answer 6

=begin
comment line 1
comment line 2
=end

make sure =begin and =end is the first thing on that line (no spaces)

Scarcely

Answer 7

Here is an example :

=begin 
print "Give me a number:"
number = gets.chomp.to_f

total = number * 10
puts  "The total value is : #{total}"

=end

Everything you place in between =begin and =end will be treated as a comment regardless of how many lines of code it contains between.

Note: Make sure there is no space between = and begin:

• Correct: =begin
• Wrong: = begin

Terreverte

Answer 8

=begin
(some code here)
=end

and

# This code
# on multiple lines
# is commented out

are both correct. The advantage of the first type of comment is editability—it's easier to uncomment because fewer characters are deleted. The advantage of the second type of comment is readability—reading the code line by line, it's much easier to tell that a particular line has been commented out. Your call but think about who's coming after you and how easy it is for them to read and maintain.

Gram

IMO, =begin and =end do not visually convey that what is in-between is a comment... Clojure, for example, uses (comment :whatever) which at leads says what it means: https://mcmap.net/q/54861/-block-comments-in-clojure – Fair

Neither do "/*" and "*/" in Java, C and C++. As with the Ruby syntax, large blocks of code might be commented out between those two characters, and everyone who knows the basics of the language knows what they mean. – Gram

Syntax coloring (in vim, for example) shows that the first type is a comment. In that case, the first type has no disadvantages. – Cnut

Answer 9

In case someone is looking for an alternate way to comment multiple lines, for instance:

<%
=begin
%>
  ... multiple HTML lines to comment out
  <%= image_tag("image.jpg") %>
<%
=end
%>

can be replaced with:

<% if false # The following section is commented out because... %>
  ... multiple HTML lines to comment out
  <%= image_tag("image.jpg") %>
<% end # if false %>

This is not strictly commenting, because there is an if sentence, and therefore there is a very small use of the CPU, so I wouldn't use this kind of resource inside code that runs frequently.

However sometimes I find it more appealing.

Does anyone know if there is a difference in main memory usage with this practice?

Adoptive

The multi line comment with begin and end, like your first code snippet, actually works. – Gorilla

@Robert, you are right! Maybe it failed with an older Ruby version... IDK anymore. I'll update the answer. Thanks! – Adoptive

Answer 10

  def idle
    <<~aid
    This is some description of what idle does.

    It does nothing actually, it's just here to show an example of multiline
    documentation. Thus said, this is something that is more common in the
    python community. That's an important point as it's good to also fit the
    expectation of your community of work. Now, if you agree with your team to
    go with a solution like this one for documenting your own base code, that's
    fine: just discuss about it with them first.

    Depending on your editor configuration, it won't be colored like a comment,
    like those starting with a "#". But as any keyword can be used for wrapping
    an heredoc, it is easy to spot anyway. One could even come with separated
    words for different puposes, so selective extraction for different types of
    documentation generation would be more practical. Depending on your editor,
    you possibly could configure it to use the same syntax highlight used for
    monoline comment when the keyword is one like aid or whatever you like.

    Also note that the squiggly-heredoc, using "~", allow to position
    the closing term with a level of indentation. That avoids to break the visual reading flow, unlike this far too long line.
    aid
  end

Note that at the moment of the post, the stackoverflow engine doesn't render syntax coloration correctly. Testing how it renders in your editor of choice is let as an exercise. ;)

Pinkster