Comments and documentation in Ruby

Introduction

Comments help explain what your code does in simple words. Documentation tells others how to use your code easily.

When you want to explain why a piece of code exists.

When you want to remind yourself what a tricky part of code does.

When you want to help others understand how to use your code.

When you want to temporarily stop a line of code from running.

When you write a method and want to describe its purpose and inputs.

Syntax

Ruby

# This is a single-line comment
=begin
This is a
multi-line comment
=end

# Documentation example:
# Adds two numbers and returns the result
# @param a [Integer] the first number
# @param b [Integer] the second number
# @return [Integer] the sum of a and b
def add(a, b)
  a + b
end

Single-line comments start with # and go to the end of the line.

Multi-line comments use =begin and =end on their own lines.

Examples

A simple single-line comment before a print statement.

Ruby

# This is a comment explaining the next line
puts "Hello, world!"

Multi-line comment that does not run, then a print statement.

Ruby

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

Documentation comments before a method to explain its purpose and parameters.

Ruby

# Calculates the square of a number
# @param x [Integer] number to square
# @return [Integer] squared result
def square(x)
  x * x
end

Sample Program

This program uses comments to explain each part: the method, the inputs, and the output.

Ruby

# This program adds two numbers and shows the result

# Define a method to add two numbers
# a and b are the inputs
# Returns their sum

def add(a, b)
  a + b
end

# Call the method and store the result
result = add(5, 7)

# Show the result
puts "The sum of 5 and 7 is #{result}"

Important Notes

Comments do not affect how the program runs.

Use comments to make your code easier to understand for yourself and others.

Keep comments clear and short.

Summary

Comments explain code and start with # for single lines.

Multi-line comments use =begin and =end.

Documentation comments describe methods and their inputs/outputs.

Practice

1. What symbol is used to start a single-line comment in Ruby?

easy

A. #

B. //

C.

D. /*

Solution

1. Step 1: Identify single-line comment syntax in Ruby

   Ruby uses # to start a single-line comment.

2. Step 2: Compare with other options

   Options A, B, and C are comment symbols from other languages (JavaScript, HTML, C-style).

3. Final Answer:

   # -> Option A

4. Quick Check:

   Single-line comment = # [OK]

Hint: Single-line comments start with # in Ruby [OK]

Common Mistakes:

• Confusing Ruby comments with C-style or HTML comments
• Using // instead of #
• Trying to use /* */ for single-line comments

2. Which of the following is the correct way to write a multi-line comment in Ruby?

easy

A. //
This is a multi-line comment
//

B. /*
This is a multi-line comment
*/

C.

D. =begin
This is a multi-line comment
=end

Solution

1. Step 1: Recall Ruby multi-line comment syntax

   Ruby uses =begin and =end to mark multi-line comments.

2. Step 2: Check other options

   Options B, C, and D are multi-line comment styles from other languages (C, HTML, JavaScript).

3. Final Answer:

   =begin This is a multi-line comment =end -> Option D

4. Quick Check:

   Multi-line comment = =begin ... =end [OK]

Hint: Use =begin and =end for multi-line comments in Ruby [OK]

Common Mistakes:

• Using /* */ which is not valid in Ruby
• Using HTML style comments
• Trying to use // for multi-line comments

3. What will be the output of this Ruby code?

def greet(name)
  # This method returns a greeting message
  "Hello, #{name}!"
end

puts greet("Alice")

medium

A. greet

B. # This method returns a greeting message

C. Hello, Alice!

D. SyntaxError

Solution

1. Step 1: Understand the method and comment

   The comment line is ignored by Ruby and does not affect output. The method returns "Hello, #{name}!" with name replaced.

2. Step 2: Check the output of puts greet("Alice")

   It prints the string "Hello, Alice!" to the console.

3. Final Answer:

   Hello, Alice! -> Option C

4. Quick Check:

   Comment ignored, method returns greeting [OK]

Hint: Comments don't print; method returns greeting string [OK]

Common Mistakes:

• Thinking comments print output
• Confusing method name with output
• Expecting comment text to appear

4. Identify the error in this Ruby code snippet:

  =begin
This is a multi-line comment
# Another comment line
  =end
puts "Done"

medium

A. =begin and =end must be at the start of the line

B. The # inside multi-line comment causes error

C. Missing closing =end

D. Multi-line comment syntax is correct

Solution

1. Step 1: Check multi-line comment syntax rules

   In Ruby, =begin and =end must be at the start of the line with no leading spaces.

2. Step 2: Analyze the given code

   If =begin or =end are indented or not at line start, Ruby raises a syntax error.

3. Final Answer:

   =begin and =end must be at the start of the line -> Option A

4. Quick Check:

   Multi-line comment markers must start line [OK]

Hint: =begin and =end must start the line exactly [OK]

Common Mistakes:

• Indenting =begin or =end
• Thinking # inside multi-line comment causes error
• Forgetting to close multi-line comment

5. You want to document a Ruby method that takes a number and returns its square. Which comment style best describes the method's purpose and input/output?

hard

A. =begin
Squares a number
Input: num
Output: squared number
=end

B. # This method squares a number
# @param num [Integer] the number to square
# @return [Integer] the squared result

C. // Squares a number
// Input: num
// Output: squared number

D.

Solution

1. Step 1: Identify proper Ruby documentation comment style

   Ruby uses single-line comments with tags like @param and @return to document methods clearly.

2. Step 2: Compare options

   # This method squares a number # @param num [Integer] the number to square # @return [Integer] the squared result uses Ruby documentation style. =begin Squares a number Input: num Output: squared number =end uses multi-line comment but lacks tags. Options C and D use invalid comment styles for Ruby.

3. Final Answer:

   # This method squares a number # @param num [Integer] the number to square # @return [Integer] the squared result -> Option B

4. Quick Check:

   Use # with @param and @return for Ruby docs [OK]

Hint: Use # with @param and @return to document Ruby methods [OK]

Common Mistakes:

• Using multi-line comments without tags for documentation
• Using comment styles from other languages
• Not specifying input/output clearly