<<Clean Code>> Quotes: 4. Comments

“Don’t comment bad code — rewrite it.” — Brian W. Kernighan and P. J. Plaugher

Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation.

The proper use of comments is to compensate for our failure to express ourself in code. Comments are always failures.

When you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code

Why am I so down on comments? Because they lie. Not always, and not intentionally, but too often.

Comments Do Not Make Up for Bad Code

One of the more common motivations for writing comments is bad code.

Explain Yourself in Code

It takes only a few seconds of thought to explain most of your intent in code.

Good Comments

Some comments are necessary or beneficial. Keep in mind, however, that the only truly good comment is the comment you found a way not to write.

Legal Comments

Where possible, refer to a standard license or other external document rather than putting all the terms and conditions into the comment.

Informative Comments

It is sometimes useful to provide basic information with a comment, … but it is better to use the name of the function to convey the information where possible.

Explanation of Intent

Sometimes a comment goes beyond just useful information about the implementation and provides the intent behind a decision.

Clarification

Sometimes it is just helpful to translate the meaning of some obscure argument or return value into something that’s readable. In general it is better to find a way to make that argument or return value clear in its own right; but when its part of the standard library, or in code that you cannot alter, then a helpful clarifying comment can be useful.

Before writing comments like this, take care that there is no better way, and then take even more care that they are accurate.

Warning of Consequences

Sometimes it is useful to warn other programmers about certain consequences.

TODO Comments

TODOs are jobs that the programmer thinks should be done, but for some reason can’t do at the moment. It might be a reminder to delete a deprecated feature or a plea for someone else to look at a problem. It might be a request for someone else to think of a better name or a reminder to make a change that is dependent on a planned event. Whatever else a TODO might be, it is not an excuse to leave bad code in the system.

You don’t want your code to be littered with TODOs. So scan through them regularly and eliminate the ones you can.

Amplification

A comment may be used to amplify the importance of something that may otherwise seem inconsequential.

Javadocs in Public APIs

There is nothing quite so helpful and satisfying as a well-described public API. The Javadocs for the standard Java library are a case in point.

Bad Comments

Mumbling

Plopping in a comment just because you feel you should or because the process requires it, is a hack. If you decide to write a comment, then spend the time necessary to make sure it is the best comment you can write.

Any comment that forces you to look in another module for the meaning of that comment has failed to communicate to you and is not worth the bits it consumes.

Redundant Comments

What purpose does this (redundant) comment serve? It’s certainly not more informative than the code. It does not justify the code, or provide intent or rationale. It is not easier to read than the code. Indeed, it is less precise than the code and entices the reader to accept that lack of precision in lieu of true understanding.

Misleading Comments

Sometimes, with all the best intentions, a programmer makes a statement in his comments that isn’t precise enough to be accurate

Mandated Comments

It is just plain silly to have a rule that says that every function must have a java doc, or every variable must have a comment.

Journal Comments

Sometimes people add a comment to the start of a module every time they edit it. … Long ago there was a good reason to create and maintain these log entries at the start of every module. We didn’t have source code control systems that did it for us. Nowadays, however these long journals are just more clutter to obfuscate the module. They should be completely removed.

Noise Comments

Sometimes you see comments that are nothing but noise. They restate the obvious and provide no new information.

Replace the temptation to create noise with the determination to clean your code.

Don’t Use a Comment When You Can Use a Function or a Variable

// does the module from the global list <mod> depend on
// subsystem we are part of?
If (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))

This could be rephrased without the comment as

ArrayList moduleDependees = module.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))

Position Markers

// Actions //////////////////////////////////

There are rare times when it makes sense to gather certain functions together beneath a banner like this. But in general they are clutter that should be eliminated — especially the noisy train of slashes at the end.

Closing Brace Comments

try {
  while ((line = in.readLine()) != null) {
    ...
  } // while
  ...
} // try

Although this might make sense for long functions with deeply nested structures, it serves only to clutter the kind of small and encapsulated functions that we prefer.

Attributions and Bylines

/* Added by Rick */

Source code control systems are very good at remembering who added what, when. There is no need to pollute the code with little bylines.

Commented-Out Code

Others who see that commented-out code won’t have the courage to delete it. They’ll think it is there for a reason and is too important to delete. So commented-out code gathers like dregs at the bottom of a bad bottle of wine.

HTML Comments

If comments are going to be extracted by some tool(like Javadocs) to appear in a Web page, then it should be the responsibility of that tool, and not the programmer, to adorn the comments with appropriate HTML.

Nonlocal Information

If you must write a comment, then make sure it describes the code it appears near.

Too Much Information

Don’t put interesting historical discussions or irrelevant descriptions of details into your comments.

Inobvious Connection

The purpose of a comment is to explain code that does not explain itself. It is a pity when a comment needs its own explanation.

Function Headers

Short functions don’t need much description. A well-chosen name for a small function that does one thing is usually better than a comment header.

Javadocs in Nonpublic Code

As useful as Javadocs are for public APIs, they are anathema to code that is not intended for public consumption.