Ruby Comments

Document your code effectively

💬 Ruby Comments

Comments are notes in your code that Ruby ignores when running programs. They help explain what your code does, making it easier for you and others to understand later. Good comments improve code readability. 


# This is a comment
puts "Hello, World!"  # This prints a message

Output: 

Hello, World!

Types of Comments

📝

Single-Line

Comments on one line using # 

# This is a comment
puts "Hello"
📄

Multi-Line

Comments spanning multiple lines 

=begin
Multi-line
comment
=end
📌

Inline

Comments after code on same line 

x = 5  # Set value
📚

Documentation

Explain methods and classes 

# Calculates sum
def add(a, b)
  a + b
end

🔹 Single-Line Comments

Single-line comments start with the # symbol and continue until the end of the line. They're the most common type of comment in Ruby. 

# This is a single-line comment
puts "Hello, Ruby!"

# Calculate the sum of two numbers
x = 10
y = 20
sum = x + y  # Add x and y

# Display the result
puts "Sum: #{sum}"

Output: 

Hello, Ruby!
Sum: 30

🔹 Multi-Line Comments

For longer explanations, Ruby provides multi-line comments using =begin and =end. These must start at the beginning of a line with no leading spaces. 

=begin
This is a multi-line comment.
It can span multiple lines.
Useful for longer explanations.
Author: Ruby Developer
Date: 2024
=end

puts "Multi-line comments are useful!"

=begin
The following code calculates
the area of a rectangle
=end

width = 10
height = 5
area = width * height
puts "Area: #{area}"

Output: 

Multi-line comments are useful!
Area: 50

🔹 Inline Comments

Inline comments appear on the same line as code, after the statement. They're useful for quick explanations of specific lines. 

# Variable declarations
name = "Alice"      # Store user name
age = 25            # Store user age
city = "New York"   # Store user city

# Display information
puts "Name: #{name}"    # Print name
puts "Age: #{age}"      # Print age
puts "City: #{city}"    # Print city

Output: 

Name: Alice
Age: 25
City: New York

🔹 Commenting Best Practices

Good comments explain why code exists, not what it does. Write clear, concise comments that add value to your code.

Good Comment Practices:

  • Explain why: Not what the code does
  • Keep updated: Update comments when code changes
  • Be concise: Short and to the point
  • Use proper grammar: Write complete sentences
  • Avoid obvious: Don't state the obvious

🔸 Bad Comments (Too Obvious) 

# Set x to 5
x = 5

# Print x
puts x

🔸 Good Comments (Explain Why) 

# Maximum retry attempts before giving up
max_retries = 5

# Display current retry count for debugging
puts "Retries: #{max_retries}"

🔹 Commenting Out Code

Comments are useful for temporarily disabling code during testing or debugging without deleting it: 

# Active code
puts "This will run"

# Temporarily disabled
# puts "This won't run"
# x = 10
# puts x

puts "This will also run"

=begin
Multiple lines disabled for testing
puts "Line 1"
puts "Line 2"
puts "Line 3"
=end

Output: 

This will run
This will also run

🔹 Documentation Comments

Use comments to document methods, classes, and complex logic. This helps other developers understand your code: 

# Calculates the factorial of a number
# Returns the factorial as an integer
def factorial(n)
  return 1 if n <= 1  # Base case
  n * factorial(n - 1)  # Recursive call
end

# Test the method
puts factorial(5)  # Should output 120

# User class to store user information
class User
  # Initialize with name and email
  def initialize(name, email)
    @name = name    # Store name
    @email = email  # Store email
  end
  
  # Display user information
  def display
    puts "Name: #{@name}, Email: #{@email}"
  end
end

# Create and display a user
user = User.new("Bob", "[email protected]")
user.display

Output: 

120
Name: Bob, Email: [email protected]

🔹 TODO Comments

Use TODO comments to mark areas that need future work or improvements: 

# TODO: Add input validation
def process_data(data)
  puts "Processing: #{data}"
end

# FIXME: This method needs optimization
def slow_method
  # Current implementation
  puts "Running slowly..."
end

# NOTE: This is a temporary solution
temp_value = 100
puts "Temp: #{temp_value}"

Output: 

Processing: sample data
Running slowly...
Temp: 100

🧠 Test Your Knowledge

What symbol starts a single-line comment in Ruby?