Skip to main content

Chapter 4: Comments Redundant Comments To Scary Noise

This page is a generated reference surface for selective reading. It exists to keep the learner apps guide-first while still preserving source access.

Learning objectives​

  • Explain the main ideas and vocabulary in Comments Redundant Comments To Scary Noise.
  • Work through the source examples for Comments Redundant Comments To Scary Noise without depending on raw chunk order.
  • Use Comments Redundant Comments To Scary Noise as selective reference when learner modules point back to Clean Code.

Prerequisites​

  • Earlier prerequisite concepts leading into Chapter 4: Comments Redundant Comments To Scary Noise.

Module targets​

  • module-01-ood-foundations-and-smells
  • module-05-applied-design-and-code-review

AI companion modes​

  • Explain simply
  • Socratic tutor
  • Quiz me
  • Challenge my understanding
  • Diagnose my confusion
  • Generate extra practice
  • Revision mode
  • Connect forward / backward

Source-of-truth note​

This unit is anchored to Clean Code and the source chapter "Chapter 4: Comments Redundant Comments To Scary Noise". Use external resources only to clarify, extend, or modernize details without replacing the chapter's conceptual spine.

External enrichment​

No chapter-specific enrichment resources are curated yet. Add them in the unit manifest when a source clearly improves learning.

Source provenance​

  • Primary source: Clean Code
  • Source chapter 04: Chapter 4: Comments Redundant Comments To Scary Noise
  • Raw source file: 022-chapter-4-comments-redundant-comments-to-scary-noise.md

Merged source​

Chapter 4 Comments Redundant Comments To Scary Noise​

Chapter 4: Comments: Redundant Comments to Scary Noise

Redundant Comments​

Listing 4-1 shows a simple function with a header comment that is completely redundant.

The comment probably takes longer to read than the code itself.

Listing 4-1

waitForClose
// Utility method that returns when this.closed is true. Throws an exception
// if the timeout is reached.
public synchronized void waitForClose(final long timeoutMillis)
  throws Exception
{
if(!closed)
{
wait(timeoutMillis);
if(!closed)
throw new Exception("MockResponseSender could not be closed");
}
}

What purpose does this 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. It is rather like a gladhanding used-car salesman assuring you that you don't need to look under the hood. Now consider the legion of useless and redundant javadocs in Listing 4-2 taken from Tomcat. These comments serve only to clutter and obscure the code. They serve no documentary purpose at all. To make matters worse, I only showed you the first few. There are many more in this module.

Listing 4-2

ContainerBase.java (Tomcat)
public abstract class ContainerBase
  implements Container, Lifecycle, Pipeline,
  MBeanRegistration, Serializable {
  /**
   * The processor delay for this component.
   */
  protected int backgroundProcessorDelay = -1;
  /**
   * The lifecycle event support for this component.
   */
  protected LifecycleSupport lifecycle =
    new LifecycleSupport(this);
  /**
   * The container event listeners for this Container.
   */
  protected ArrayList listeners = new ArrayList();
  /**
   * The Loader implementation with which this Container is
   * associated.
   */
  protected Loader loader = null;
  /**
   * The Logger implementation with which this Container is
   * associated.
   */
  protected Log logger = null;
  /**
   * Associated logger name.
   */
  protected String logName = null;

Listing 4-2 (continued)

ContainerBase.java (Tomcat)
  /**
   * The Manager implementation with which this Container is
   * associated.
   */
  protected Manager manager = null;
  /**
   * The cluster with which this Container is associated.
   */
  protected Cluster cluster = null;
  /**
   * The human-readable name of this Container.
   */
  protected String name = null;
  /**
   * The parent Container to which this Container is a child.
   */
  protected Container parent = null;
  /**
   * The parent class loader to be configured when we install a
   * Loader.
   */
  protected ClassLoader parentClassLoader = null;
  /**
   * The Pipeline object with which this Container is
   * associated.
   */
  protected Pipeline pipeline = new StandardPipeline(this);
  /**
   * The Realm with which this Container is associated.
   */
  protected Realm realm = null;
  /**
   * The resources DirContext object with which this Container
   * is associated.
   */
  protected DirContext resources = null;

Misleading Comments​

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.

Mandated Comments​

It is just plain silly to have a rule that says that every function must have a javadoc, or every variable must have a comment. Comments like this just clutter up the code, propagate lies, and lend to general confusion and disorganization. For example, required javadocs for every function lead to abominations such as Listing 4-3. This clutter adds nothing and serves only to obfuscate the code and create the potential for lies and misdirection.

Listing 4-3

  /**
   *
   * @param title The title of the CD
   * @param author The author of the CD
   * @param tracks The number of tracks on the CD
   * @param durationInMinutes The duration of the CD in minutes
   */
  public void addCD(String title, String author,
                     int tracks, int durationInMinutes) {
    CD cd = new CD();
    cd.title = title;
    cd.author = author;
    cd.tracks = tracks;
    cd.duration = duration;
    cdList.add(cd);

Journal Comments​

Sometimes people add a comment to the start of a module every time they edit it. These comments accumulate as a kind of journal, or log, of every change that has ever been made. I have seen some modules with dozens of pages of these run-on journal entries.

 * Changes (from 11-Oct-2001)
 * --------------------------
 * 11-Oct-2001 : Re-organised the class and moved it to new package
 *               com.jrefinery.date (DG);
 * 05-Nov-2001 : Added a getDescription() method, and eliminated NotableDate
 *               class (DG);
 * 12-Nov-2001 : IBD requires setDescription() method, now that NotableDate
 *               class is gone (DG);  Changed getPreviousDayOfWeek(),
 *               getFollowingDayOfWeek() and getNearestDayOfWeek() to correct
 *               bugs (DG);
 * 05-Dec-2001 : Fixed bug in SpreadsheetDate class (DG);
 * 29-May-2002 : Moved the month constants into a separate interface
 *               (MonthConstants) (DG);
 * 27-Aug-2002 : Fixed bug in addMonths() method, thanks to N???levka Petr (DG);
 * 03-Oct-2002 : Fixed errors reported by Checkstyle (DG);
 * 13-Mar-2003 : Implemented Serializable (DG);
 * 29-May-2003 : Fixed bug in addMonths method (DG);
 * 04-Sep-2003 : Implemented Comparable.  Updated the isInRange javadocs (DG);
 * 05-Jan-2005 : Fixed bug in addYears() method (1096282) (DG);

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.

/**
 * 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;
}

These comments are so noisy that we learn to ignore them. As we read through code, our eyes simply skip over them. Eventually the comments begin to lie as the code around them changes. The first comment in Listing 4-4 seems appropriate.2 It explains why the catch block is being ignored. But the second comment is pure noise. Apparently the programmer was just so frustrated with writing try/catch blocks in this function that he needed to vent.

Listing 4-4

startSending
private void startSending()
{
try
{
doSending();
}
catch(SocketException e)
{
// normal. someone stopped the request.
}
catch(Exception e)
{
try
{
response.add(ErrorResponder.makeExceptionString(e));
response.closeAll();
}
catch(Exception e1)
{
//Give me a break!
}
}
}

Rather than venting in a worthless and noisy comment, the programmer should have recognized that his frustration could be resolved by improving the structure of his code. He should have redirected his energy to extracting that last try/catch block into a separate function, as shown in Listing 4-5.

Listing 4-5

startSending (refactored)
private void startSending()
{
try
{
doSending();
}
  1. The current trend for IDEs to check spelling in comments will be a balm for those of us who read a lot of code.

Listing 4-5 (continued)

startSending (refactored)
catch(SocketException e)
{
// normal. someone stopped the request.
}
catch(Exception e)
{
addExceptionAndCloseResponse(e);
}
}
private void addExceptionAndCloseResponse(Exception e)
{
try
{
response.add(ErrorResponder.makeExceptionString(e));
response.closeAll();
}
catch(Exception e1)
{
}
}

Replace the temptation to create noise with the determination to clean your code. You'll find it makes you a better and happier programmer.

Scary Noise​

Javadocs can also be noisy. What purpose do the following Javadocs (from a well-known open-source library) serve? Answer: nothing. They are just redundant noisy comments written out of some misplaced desire to provide documentation.

/** The name. */
private String name;
/** The version. */
private String version;
/** The licenceName. */
private String licenceName;
/** The version. */
private String info;

Read these comments again more carefully. Do you see the cut-paste error? If authors aren't paying attention when comments are written (or pasted), why should readers be expected to profit from them?