Clean code — Comments

Right now I’m reading for the second time, the great book Clean Code by Robert C. Martin aka Uncle Bob and I think it’s a good idea to write down the most important ideas that it tries to convey to us. Today, I will focus on the fourth chapter.

Comments do not make up for bad code

Comments are at best, a necessary evil. If our programming languages were expressive enough, we had the talent to subtly wield those languages to express our talent, we would not need comments very much perhaps not at all.

The proper use of comments is to compensate for our failure to express ourselves in code. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration.

Why am I so down on comments? Because they lie. Not always, and not intentionally, but too often. The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers cant realistically maintain them.

Truth can only be found in one place: the code. Only the code can truly tell you what it does. It is the code source of truly accurate information. Therefore, though comments are sometimes necessary, we will expend significant energy to minimize them.

One of the more common motivations for writing comments is bad code. We know it's a mess.

Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments.

Explain yourself in code

//check to see if the employee is eligible for full benefits
if((employee.flags && HOURLY_FLAG) && (employee.age > 65))

or this?

if(employee.isEligibleForFullBenefits())

It takes only a few seconds of thought to explain most of your intent in code. In many cases, it's simply a matter of creating a function that says the same thing as the comment you want to write.

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.

Warning of Consequences

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

public static SimpleDateFormat makeStandardHttpDateFormat(){
   //SimpleDateFormat is not thread safe.
   //So we need to create each instance independently
   SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
   df.setTimeZone(TimeZone.getTimeZone("GMT"));
   return df;
}

You might complain that there are better ways to solve this problem. I might agree with you. But the comment, as given here, is perfectly reasonable. It will prevent some overly eager programmers from using a static initializer in the name of efficiency.

Javadocs in Public APIs

If you are writing a public API, then you should certainly write good JavaDocs for it. But keep in mind the rest of the advice in this chapter. JavaDocs can be just as misleading, nonlocal, and dishonest as any other kind of comment.

Noise Comments

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

/**
 * Default Constructor 
 */
protected AnnualDateRule(){
}

No, really? or how about this:

/**
 * The day of the month
 */
private int dayOfMonth;

And then there's this paragon of redundancy:

/**
 * Returns the day of the month
 *
 * @Return the day of the month
 */
public int getDayOfMonth(){
   return dayOfMonth;
}

Don't use a comment when you can use a Function or a Variable

Consider the following stretch of code:

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

This could be rephrased without the comment as:

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

Nonlocal information

If you must write a comment, then make sure it describes the code it appears near. Don't offer systemwide information in the context of the local comment.

Conclusions

The most important idea I keep on this is “Don’t write comments if you can explain it in code.” Reducing comments to a minimum and understanding the code speaks of that being good code.