As comments are not executable, they are easily out of date. They are a form of decaying documentation.

If the code inside a method needs a comment, you probably can extract the code into a new method whose name explains what you need to clarify.

Moreover, the Single Responsibility Principle says that classes and methods should have a single responsibility so when you need comments they probably have more than one responsibility.

Therefore instead of:

def gear_inches
  # tire goes around rim twice for diameter
  ratio * rim + (tire * 2)
end

The following is clearer and needs no comment:

def gear_inches
  ratio * diameter
end

def diameter
  rim + (tire * 2)
end

Examples from POODR and here.

Categories: Ruby on Rails & other tech

Tags: POODR