Tidy First?

Chapter 15. Delete Redundant Comments

When you see a comment that says exactly what the code says, remove it.

The purpose of code is to explain to other programmers what you want the computer to do. Comments and code present different trade-offs for you as a writer and for future readers. You can explain anything you want in prose. On the other hand, there’s no mechanism to double-check the accuracy of prose as the system changes, and comments might become redundant as the code evolves.

Some folks take a narrow view of the mandate to communicate, insisting on dogmatic rules like one stating that every routine must be commented. This results in comments like:

getX()
  # return X
  return X

This comment provides costs without benefits. As a writer, you’ve just wasted the reader’s time—​time they can’t recover. If a comment is completely redundant, then delete it.

Tidyings often chain together. A previous tidying may have made a comment redundant. For example, the original code might look like this:

if (generator)
    ...a bunch of lines of code to set up the generator...
else
    # no generator, return the default
    return getDefaultGenerator()

After tidying with a guard clause, the code looks like this:

if (! generator)
    # no generator, return the default
    return getDefaultGenerator()

...a bunch of lines of code to set up the generator...

The comment isn’t redundant at first. It returns our attention to the current context (no generator present) after reading a bunch of lines of code in a different ...