Ruby Science


Comments can be used appropriately to introduce classes and provide documentation. But used incorrectly, they mask readability and process problems by further obfuscating already unreadable code.


  • Comments within method bodies.
  • More than one comment per method.
  • Comments that restate the method name in English.
  • Todo comments.
  • Commented out, dead code.


# app/models/open_question.rb
def summary
  # Text for each answer in order as a comma-separated string
  answers.order().pluck().join(', ')

This comment is trying to explain what the following line of code does because the code itself is too hard to understand. A better solution would be to improve the legibility of the code.

Some comments add no value at all and can safely be removed:

class Invitation
  # Deliver the invitation
  def deliver
    Mailer.invitation_notification(self, message).deliver

If there isn’t a useful explanation to provide for a method or class beyond the name, don’t leave a comment.


  • Introduce explaining variable to make obfuscated lines easier to read in pieces.
  • Extract method to break up methods that are difficult to read.
  • Move todo comments into a task management system.
  • Delete commented out code and rely on version control in the event that you want to get it back.
  • Delete superfluous comments that don’t add more value than the method or class name.

Ruby Science

The canonical reference for writing fantastic Rails applications from authors who have created hundreds.

Work with us to make a new Rails app, or to maintain, improve, or scale your existing app.