Coding Harry's Key Ideas from Clean Code
by Robert C. Martin

Sometimes our corporate coding standards force us to write certain comments for legal reasons. For example, copyright and authorship statements are necessary and reasonable things to put into a comment at the start of each source file.

Here, for example, is the standard comment header that we put at the beginning of every source file in FitNesse. I am happy to say that our IDE hides this comment from acting as clutter by automatically collapsing it.

/ Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.

It is sometimes useful to provide basic information with a comment. For example, consider this comment that explains the return value of an abstract method:

/ Returns an instance of the Responder being tested. protected abstract Responder responderInstance ();

A comment like this can sometimes be useful, but it is better to use the name of the function to convey the information where possible. For example, in this case the comment could be made redundant by renaming the function: responderBeingTested.

Here's a case that's a bit better:

// format matched kk:mm:ss EBE, MMM dd, yyyy

Pattern timeMatcher = Pattern. compile (

"'|d*: 11d*: 1 1d* Ww*, Ww* Nd*, lId* n) :

In this case the comment lets us know that the regular expression is intended to match a time and date that were formatted with the SimpleDateFormat. format function using the specified format string. Still, it might have been better, and clearer, if this code had been moved to a special class that converted the formats of dates and times. Then the comment would likely have been superfluous.

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.

Nowadays, most good IDEs provide special gestures and features to locate all the TODO comments, so it's not likely that they will get lost. Still, you don't want your code to be littered with TODOs. So scan through them regularly and eliminate the ones you can.

Most comments fall into this category. Usually they are crutches or excuses for poor code or justifications for insufficient decisions, amounting to little more than the programmer talking to himself.

Sometimes, with all the best intentions, a programmer makes a statement in his comments that isn't precise enough to be accurate. Consider for another moment the badly redundant but also subtly misleading comment we saw in Listing 4-1.

Did you discover how the comment was misleading? The method does not return when this.closed becomes true. It returns if this.closed is true; otherwise, it waits for a blind time-out and then throws an exception if this closed is still not true.

This subtle bit of misinformation, couched in a comment that is harder to read than the body of the code, could cause another programmer to blithely call this function in the expectation that it will return as soon as this .closed becomes true. That poor programmer would then find himself in a debugging session trying to figure out why his code executed so slowly.