Comments are usually an excuse for bad code. Instead of wasting time trying to come up with comments for your code, try to refactor it so it’s self explanatory. Most of the time you won’t need comments if you care about your code.

There are few ocassions when comments can be helpful. Keeping comments up to date takes effort, and I’d rather improve my system than waste time keeping up to date comments for bad code.

Most of the comments can be removed my renaming a function or variable. Consider:

# Parse an HTML string
p = Parser.new
p.run(str)

What kind of format does this parser take in? What’s does str hold? You can’t tell by reading the code so a developer might add comments to answer those questions.

Those same questions can be answered without comments.

parser = Parser::HTML
parser.parse(html_string)