Ruby Comments and Documentation
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.
# 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)
endDocumentation 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.
# 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)
endMany 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/=endblock 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?
You May Also Like
Hello World and Ruby Syntax
Write your first Ruby program and learn the fundamental syntax conventions: statements, indentation, method calls, and file structure.
Defining Methods
How to define methods in Ruby using def, including implicit return values, naming conventions (?, !), visibility, and how methods differ from blocks.
Bundler and Gems
Understand how RubyGems packages and distributes Ruby libraries, and how Bundler locks dependency versions with a Gemfile and Gemfile.lock for reproducible builds.
Ruby Quick Reference
A condensed cheat sheet of core Ruby syntax, common Enumerable methods, and idioms for fast lookup while coding.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics