Ruby Comments and Documentation

Analogy categoryAnalogies

Comments let you annotate code with explanations that the Ruby interpreter ignores at runtime, helping future readers (including yourself) understand intent, edge cases, and reasoning that the code alone cannot convey. Beyond ad hoc comments, Ruby has a documentation culture built around tools like RDoc and YARD, which parse specially formatted comments to generate browsable API documentation, similar in spirit to Javadoc or Python's docstrings, though structured differently.

🏏

Cricket analogy: Comments are like a coach's notes scrawled in the margins of a match plan, invisible to the players executing it but invaluable to future analysts; YARD is like a formal scouting report generated from those notes for the whole team to browse.

Single-line and Multi-line Comments

A single-line comment starts with # and extends to the end of the line; everything after the # on that line is ignored. Ruby does not have a dedicated multi-line comment token like /* */ in C-family languages, but it does support block comments using =begin and =end, which must start at the beginning of a line. In practice, most Ruby style guides discourage =begin/=end blocks in favor of consecutive # lines, since block comments are easy to accidentally leave uncommented or nest incorrectly.

🏏

Cricket analogy: A single-line # comment is like a quick chalk mark on the scoreboard noting one observation, while Ruby has no /* */ block comment token — the =begin/=end equivalent is discouraged, much like a coach avoiding a messy whiteboard essay mid-innings.

ruby

# This is a single-line comment explaining the next line
total = price * quantity  # inline comment explaining this expression

=begin
This is a block comment.
It can span multiple lines,
but is rarely used in idiomatic Ruby style.
=end

# Preferred style for multi-line explanations:
# Calculates the final price including tax.
# Assumes tax_rate is a decimal, e.g. 0.08 for 8%.
def final_price(price, tax_rate)
  price + (price * tax_rate)
end

Documentation Comments with YARD

YARD (Yay! A Ruby Documenter) is the de facto modern standard for documenting Ruby code, superseding the older RDoc format in most gem ecosystems, though RDoc remains Ruby's built-in default tool. YARD comments use @param, @return, @raise, and similar tags placed directly above a method definition, allowing tools to generate structured HTML documentation and enabling IDEs to provide better autocomplete and type hints, even in a dynamically typed language.

🏏

Cricket analogy: YARD is like the modern digital scoring app that replaced the old paper scorebook (RDoc), using standardized tags like @param and @return the way a scorecard uses standardized columns for runs, balls, and wickets so anyone can read it instantly.

ruby

# Calculates the final price of an item including tax.
#
# @param price [Float] the pre-tax price of the item
# @param tax_rate [Float] the tax rate as a decimal (e.g. 0.08)
# @return [Float] the total price including tax
def final_price(price, tax_rate)
  price + (price * tax_rate)
end

Many gems publish their generated YARD documentation to rubydoc.info, which is the closest Ruby equivalent to Python's readthedocs.io or JavaScript's generated TypeDoc sites.

It's easy to let comments drift out of sync with the code they describe. A comment that contradicts the code it annotates is often worse than no comment at all, since it actively misleads readers; treat comments as something to update in the same commit as the code change.

Single-line comments start with # and run to the end of the line.
Ruby supports =begin/=end block comments, but idiomatic style prefers consecutive # lines.
YARD is the modern standard for structured documentation comments, using tags like @param and @return.
RDoc is Ruby's built-in default documentation tool, though YARD has largely superseded it in the gem ecosystem.
Well-written comments explain 'why', not just 'what', since the code itself already shows what happens.
Stale or contradictory comments actively mislead readers and should be updated alongside code changes.

Practice what you learned

1. How does a single-line comment begin in Ruby?

2. What keywords delimit a Ruby block comment?

3. Which documentation tool is now the de facto standard for Ruby gems, superseding RDoc in most cases?

4. Which YARD tag documents the return value of a method?

5. Why are stale comments considered problematic?

Was this page helpful?

Variables and Data Types

Related Study Notes in Programming

Browse all study notes

Programming

Apache Spark Study Notes

Programming · 30 topics

Programming

Apache Flink Study Notes

Programming · 30 topics

Programming

Hadoop Study Notes

Programming · 30 topics

Programming

Snowflake Study Notes

Programming · 30 topics

Programming

Apache Airflow Study Notes

Programming · 30 topics

Programming

dbt (Data Build Tool) Study Notes

Programming · 30 topics

Topics covered

#Ruby#RubyStudyNotes#Programming#RubyCommentsAndDocumentation#Comments#Documentation#Single#Line#StudyNotes#SkillVeris

Ruby Comments and Documentation