Comment

Don't comment bad code, rewrite it!

• Too often, the comments get separated from the code they describe.

• Inaccurate comments are far worse than no comments at all.

• Minimize it. Clean code don't need the comments in the first place.

Comments Do Not Make Up for Bad Code

"Ooh, I'd better comment that!" No! You'd better clean it!

Explain Yourself in Code

Bad code:

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

Clean code:

if (employee.isEligibleForFullBenefits())

Good Comments

Legal Comments

// Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.
// Released under the terms of the HNU General Public License version 2 or later.

Refer to a standard license or other external document rather than putting all the terms and conditions into the comment.

Informative Comments

// format matched kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile(
    "\\d*":\\d*:\\d* \\w*, \\w* \\d*, \\d*");

Clarification

When its part of the standard library, or in code that you cannot alter, then a helpful clarifying comment can be useful.

public void testCompareTo() throws Exception {

    WikiPagePath a = PathParse.parse("PageA");
    WikiPagePath ab = PathParse.parse("PageA.PageB");
    WikiPagePath b = PathParse.parse("PageB");
    WikiPagePath aa = PathParse.parse("PageA.PageA");
    WikiPagePath bb = PathParse.parse("PageB.PageB");
    WikiPagePath ba = PathParse.parse("PageB.PageA");

    assertTrue(a.compareTo(a) == 0);        // a == a
    assertTrue(a.compareTo(b) == 0);        // a != a
    assertTrue(ab.compareTo(ab) == 0);      // ab == ab
    assertTrue(a.compareTo(b) == -1);       // a < b
    assertTrue(aa.compareTo(ab) == -1);     // aa < ab
    assertTrue(ba.compareTo(bb) == -1);     // ba < bb
    assertTrue(b.compareTo(a) == 1);        // b > a
    assertTrue(ab.compareTo(aa) == 1);      // ab > aa
    assertTrue(bb.compareTo(ba) == 1);      // bb > ba

}

Warning of Consequences

// Don't run unless you have some time to kill.
public oid _testWithReallyBigFile() {
    ...
}

TODO Comments

// TODO We expect this to go away when we do the checkout model
protected VersionInfo makeVersion() throws Exception {
    return null;
}

Javadocs in Public APIs

Javadocs is used for generating the document automatically if the developers write the comments following its format.

Bad Comments

Redundant Comments

/**
 * The processor delay for this component.
 */
protected int backgroundProcessorDelay = -1;

/**
 * The lifecycle event support for this compoent.
 */
protected LifecycleSupport lifecycle = new LifecycleSupport(this);

...

Noise Comments

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

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

Position Markers

// I'm here!!! ///////////////////////////////

Use them very sparingly, or your eyes will get used to ignoring it. Group the code in different files, or just by line breaks.

Closing Brace Comments

if( ... ) {
    while( ... ) {
        catch ( ... ) {
            ...
        } // catch
    } // while
} // if

Commented-Out Code

Don't do this! You have Git (or other version control tool)! Just delete it!

InputStreamResponse response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// InputStream resultsStream = formatter.getResultStream();
// StreamReader reader = new StreamReader(resultsStream);
// response.setContent(reader.read(formatter.getByteCount()));

Others

• Attributions and Bylines, like: /* Added by Rick */

• HTML Comments

• Too Much Information

• Javadocs in Nonpublic Code