Ruby Multiline Comments Explained with Examples

Ruby, known for its elegant and developer-friendly syntax, handles comments in a somewhat unique way compared to many other programming languages. While single-line comments (starting with #) are ubiquitous and widely used, multiline (or block) comments have a dedicated syntax that many Ruby developers rarely touch in day-to-day work. This article dives deep into Ruby’s multiline comment system — how it works, why it’s designed this way, its quirks, best practices, common pitfalls, real-world use cases, and plenty of practical examples. We’ll cover both the official block comment syntax (=begin / =end) and the far more common idiom of using multiple single-line comments to achieve the same effect. By the end, you’ll understand exactly when (and when not) to use each approach.

1. Ruby’s Two Comment Types: Inline vs Block

According to the official Ruby documentation (ruby-lang.org syntax reference), Ruby supports exactly two kinds of code comments:

• Inline comments — start with # and continue until the end of the line
• Block comments — start with =begin (on its own line) and end with =end (also on its own line)

Inline comments are by far the most common. They can appear:

• On a line by themselves
• After code on the same line
• Indented inside blocks

rubis

# This is a standalone comment

name = "Alice"          # inline comment after code

class User
  # Documentation comment inside a class
  def initialize(name)
    @name = name
  end
end

Block comments, on the other hand, are Ruby’s true multiline comment mechanism — but they come with strict rules and limited practical use.

2. The =begin / =end Block Comment Syntax

The official multiline comment syntax looks like this:

rubis

=begin
This is a multiline comment block.
Everything between =begin and =end is ignored by the Ruby parser.

You can write as many lines as you want here.
No need to prefix each line with #.

This is useful for long explanations, copyright notices,
or temporarily disabling large sections of code.
=end

puts "This line runs normally"

Key rules (these are enforced by the parser):

1. =begin must appear alone at the beginning of a line (no leading whitespace allowed).
2. =end must also appear alone at the beginning of a line (no leading whitespace).
3. Both markers must start in column 1 (leftmost position).
4. The content between them can be indented freely — only the markers themselves cannot be indented.
5. The block comment ends at the first =end that appears at the start of a line.

Because of rule #1 and #2, this syntax cannot be used inside indented blocks such as methods, classes, modules, or conditionals.

rubis

def calculate_total(items)
  =begin               # ← Syntax error!
  This won't work because =begin is indented
  =end
  items.sum
end

Trying to run the above code produces a syntax error:

syntax error, unexpected '=', expecting `end'
  =begin
   ^

This indentation restriction is the single biggest reason most experienced Ruby developers avoid =begin / =end in everyday code.

3. The Practical Multiline Comment: Multiple # Lines

Because true block comments are so restrictive, the community-standard way to comment out or document multiple lines is simply to prefix each line with #:

rubis

# This is the most common way to write multiline comments in Ruby
# You can comment out an entire method like this:
# def old_broken_method
#   puts "This was causing errors"
#   do_dangerous_stuff!
#   crash_the_program
# end

# Or write longer documentation:
# Calculates the factorial of n using recursion.
# Warning: very slow for large n (> ~1000)
# For production code prefer the iterative version.
# Examples:
#   factorial(5)  # => 120
#   factorial(0)  # => 1
def factorial(n)
  return 1 if n <= 1
  n * factorial(n - 1)
end

Modern editors and IDEs (VS Code, RubyMine, Sublime, Vim with plugins, etc.) make this trivial:

• Highlight multiple lines → press Ctrl+/ (or Cmd+/ on macOS) → every line gets a # prefix
• Press the same shortcut again → removes the prefixes

This workflow is so fast and reliable that most Rubyists never feel the need for =begin / =end.

4. Comparing the Two Approaches Side-by-Side

5. Special Use Cases Where =begin / =end Still Appears

Even though it’s uncommon, the block comment syntax is occasionally useful or encountered in the wild.

A. Embedded / RDoc / YARD documentation at the top of a file

Many Ruby core files and older gems use block comments for long file-level documentation:

rubis

=begin rdoc

= Overview

This module provides utilities for date/time calculations
that are timezone-aware and support business days.

=end

module BusinessTime
  # ... rest of the code
end

The =begin rdoc marker tells RDoc/YARD parsers that this is documentation (not regular code comment). Some tools also support =begin pod, =begin markdown, etc.

B. Conditional file sections during development

Sometimes you’ll see developers use block comments to quickly disable entire sections at the top level:

rubis

=begin
require 'expensive_debug_gem'
require 'memory_profiler'

MemoryProfiler.report do
  # very slow code here
end
=end

# Normal app code continues...

Because it’s at the top level (not indented), =begin / =end works perfectly here.C. Legacy code or code generationYou may encounter =begin / =end in very old Ruby 1.8/1.9 codebases, Rails plugin skeletons, or code generated by tools.

6. Common Pitfalls and Mistakes

Mistake 1: Indenting the markers

rubis

  =begin          # ← Syntax error
    important note
  =end

Mistake 2: Forgetting that =end must be alone

rubis

=begin
stuff
=end some note     # ← Syntax error, parser keeps looking for =end

Mistake 3: Expecting nested block comments

rubis

=begin
outer comment
  =begin
  inner comment   # ← ignored, treated as normal text
  =end
more outer
=end

Block comments do not nest.

Mistake 4: Using block comments for TODOs inside methods

Developers sometimes try this — and immediately regret it when they see the syntax error.

7. Best Practices for Commenting in Ruby (2025–2026 Style)

1. Prefer multiple # lines for almost everything.
2. Use # for inline explanations, edge-case notes, and algorithm steps.
3. Write RDoc/YARD documentation above methods/classes/modules using # lines (not =begin).
4. Reserve =begin / =end for:
   

   • File-level copyright/legal notices
   • Long RDoc markup at file start
   • Temporary top-level debugging blocks

5. Keep comments up-to-date — outdated comments are worse than no comments.
6. Use tools like rubocop — it has rules like Style/CommentAnnotation to standardize TODO/FIXME/NOTE keywords.

8. Quick Reference: All Ruby Comment Styles in One Place

rubis

# Single-line comment

# Multiline via multiple single-line comments
# Line 2
# Line 3

=begin
True block comment.
Can span many lines.
No # needed on each line.
=end

=begin rdoc          # Special for documentation tools
= Heading

Explanation paragraph.

* list item
* another
=end

class Example
  # This is allowed (indented inline comment)
  def demo
    # Everything here uses #
    # No =begin possible here
  end
end

Conclusion

Ruby’s multiline comment story is simple once you accept one fact: the idiomatic way to comment multiple lines is just to use many # symbols. The =begin / =end syntax exists, is well-defined in the official language specification, and has niche uses — but in modern Ruby code (2025+), you’ll rarely see it inside methods or classes because of its indentation limitation. Mastering both approaches helps when reading legacy code, contributing to Ruby core, or working with documentation-generation tools. But for your day-to-day work? Stick with # — your future self (and your teammates) will thank you.