How to Write Multi-Line Comments in Ruby

By the end of this page, you will understand how Ruby handles comments, how to write comments across multiple lines, when to use # versus =begin and =end, and which approach is most practical in real Ruby codebases.

In Ruby, comments are used to write notes for humans without affecting how the program runs.

Ruby supports two main comment styles:

• Single-line comments with #
• Block-style comments using =begin and =end

A single-line comment looks like this:

# This is a comment

For multiple lines, the most common approach is simply to put # at the start of each line:

# This is line one
# This is line two
# This is line three

Ruby also supports a special document-style block comment syntax:

=begin
This is a multi-line comment.
It can span several lines.
=end

However, =begin and =end have an important rule:

• They must start at the beginning of the line
• They are used less often in everyday Ruby code

In real projects, developers usually prefer repeated # comments because they are clearer, easier to format, and better supported by editors and style guides.

This matters because comments are part of code readability. Good comments help explain intent, temporarily disable code during debugging, and document tricky logic. But using the right comment style makes code easier for other Ruby developers to understand and maintain.

Think of comments like sticky notes attached to your code.

• A # comment is like putting a small sticky note on one line.
• Several # lines in a row are like stacking multiple sticky notes to explain a bigger idea.
• =begin and =end are more like putting a large paper cover around a whole section.

Ruby programmers usually prefer the stack of small sticky notes because they are easier to move, edit, and read.

Single-line comment

# Print a greeting
puts "Hello"

The line starting with # is ignored by Ruby.

Multi-line comment using #

# This method calculates the total price.
# It includes tax and shipping.
# Use it when showing the checkout summary.
def total_price(subtotal, tax, shipping)
  subtotal + tax + shipping
end

This is the most common Ruby style for multi-line comments.

Multi-line comment using =begin and =end

=begin
This whole section is treated as a comment.
Ruby ignores everything until it reaches =end.
=end

puts "Hello"

Temporarily disabling code

# puts "Debug: starting process"
# puts "Debug: loading file"
puts "App is running"

This is often how developers temporarily disable code while testing.

Important formatting rule

This works:

=begin
This is valid.
=end

This does not work reliably:

  =begin
  This may cause problems.
  =end

=begin and =end should start at column 1, with no spaces before them.

Consider this example:

# Start of program
# The next line prints a message
puts "Hello, Ruby!"

Step by step:

1. Ruby reads # Start of program
   • Because the line starts with #, Ruby ignores it.
2. Ruby reads # The next line prints a message
   • This is also ignored.
3. Ruby reads puts "Hello, Ruby!"
   • This is executable Ruby code.
   • Ruby prints Hello, Ruby!

Now look at a block comment example:

=begin
This is all ignored.
So is this line.
=end

puts "Done"

Step by step:

1. Ruby sees =begin
   • It starts a block comment.
2. Ruby ignores all following lines.
3. Ruby sees =end
   • The block comment stops.
4. Ruby reads puts "Done"
   • Ruby executes it and prints Done.

Comments across multiple lines are useful in many practical situations:

• Explaining business logic
  • For example, why an invoice total includes a special discount rule.
• Documenting temporary workarounds
  • Example: a note explaining why a piece of code exists until an external API bug is fixed.
• Disabling debug code
  • Developers often comment out several puts statements while testing.
• Adding setup instructions in scripts
  • A Ruby script may include several comment lines describing required environment variables.
• Annotating examples in teaching code
  • Tutorial or sample Ruby files often use multiple # lines to explain each section.

Example:

# This script imports customer data.
# Expected input: CSV with headers.
# Rows with missing email addresses are skipped.
load_customers("customers.csv")

In real Ruby codebases, developers usually use multi-line comments in a few standard ways:

Repeated # for explanations

This is the most common pattern:

# We return early here because guest users
# should not be allowed to update billing details.
return if current_user.guest?

Commenting out code during debugging

# puts response.body
# puts response.status
process_response(response)

Guard clauses with explanation

# Skip processing if the file does not exist.
# This prevents a downstream parser error.
return unless File.exist?(path)

Validation notes

# Names are limited to 50 characters because
# the external billing service rejects longer values.
raise ArgumentError, "name too long" if name.length > 50

Why developers avoid =begin/=end in teams

• Harder to indent naturally inside methods or classes
• Less common in style guides
• Less convenient when commenting out only selected lines
• # comments are more consistent with inline comments and documentation habits

So while Ruby supports block comments, most professional Ruby code uses multiple # lines instead.

1. Assuming Ruby has C-style comments

Ruby does not use /* ... */.

Broken example:

/* This is not valid Ruby */
puts "Hello"

Use this instead:

# This is valid Ruby
puts "Hello"

2. Indenting =begin and =end

Broken example:

  =begin
  Comment text
  =end

This may not work as expected because =begin and =end should start at the beginning of the line.

Correct version:

=begin
Comment text
=end

3. Using =begin/=end inside code blocks carelessly

Because of the formatting rule, this can look awkward inside methods:

def greet
=begin
This style is valid only if aligned correctly,
but it is usually not the best choice here.
=end
  puts "Hi"
end

Prefer:

def greet
  # Explain what this method does.
  # This style fits naturally inside the method.
  puts "Hi"
end

4. Commenting too much obvious code

Not helpful:

# Add 1 to x
x = x + 1

Better:

# Retry count increases after each failed request.
retries += 1

5. Forgetting that comments should help humans

A comment should explain why, not just repeat what the code already says.

Comment styles in Ruby

# vs =begin / =end

Ruby vs some other languages

A common beginner mistake is expecting Ruby to use the same block comment syntax as JavaScript or C. It does not.

Quick reference

Single-line comment

# This is a comment

Multi-line comment, preferred style

# First line
# Second line
# Third line

Block comment syntax

=begin
This is a block comment.
It spans multiple lines.
=end

Rules

• Use # for normal comments
• Use multiple # lines for multi-line explanations
• =begin and =end must start at the beginning of the line
• Ruby does not use /* ... */
• Prefer comments that explain why, not obvious code behavior

Good practice

# Return early if the user is not logged in.
return unless current_user

Avoid

# Set name to Bob
name = "Bob"

Best default choice

If you are unsure, use multiple # lines.

How do you write a multi-line comment in Ruby?

The most common way is to put # at the start of each line. Ruby also supports =begin and =end for block comments.

Does Ruby support /* ... */ comments?

No. That syntax is used in languages like JavaScript, C, and Java, but not in Ruby.

Should I use =begin and =end in Ruby?

You can, but most Ruby developers prefer multiple # lines because they fit better with indentation and everyday coding style.

Why is =begin not working in my Ruby code?

A common reason is indentation. =begin and =end should start at the beginning of the line with no leading spaces.

What is the best way to comment out several lines in Ruby?

Usually, add # to each line. Most editors can do this automatically for selected lines.

Can I use multi-line comments inside a method in Ruby?

Yes. The easiest and most readable way is to use multiple # lines inside the method body.

Are comments ignored when Ruby runs?

Yes. Ruby ignores comments, so they do not affect execution unless you accidentally break syntax around them.

Single-line comments

The basic Ruby comment style. Multi-line comments are often just several single-line comments together.

Ruby syntax basics

Understanding comments is part of learning how Ruby source code is structured.

Methods in Ruby

Comments are often used above methods to explain behavior, inputs, or edge cases.

Guard clauses in Ruby

Developers frequently place short explanatory comments above early returns.

Debugging in Ruby

Commenting out lines temporarily is a common debugging technique.

Code readability

Comments are one part of writing code that other developers can understand and maintain.