don't like comments. They are often so useless that I usually don't read them. Ever since my older brother caught me typing REM statements into a program as a child and then broke the news to me that they did absolutely nothing, I've developed a keen distrust of comments. This opinion only solidified when I pursued my computer science degree. I realized that my classmates and I wrote comments only to earn good marks from mean-spirited instructors who were more concerned with whether our code was commented than whether it worked correctly! Simply put, I felt that comments were a waste of time.

My dislike of comments is based on the following reasoning:

• In most cases, comments are written by programmers who don't believe in them.
• Comments rarely reflect what is really happening in the code.
• Well-written code should not need comments. Of course, there are exceptions. For example, interfaces need very detailed comments to define the various conditions. If you have methods named f(), g(), and h(), you will need to document what the methods do. But why not call them something sensible in the first place?
• Instead of writing long pre- and post-conditions in the comments, why not write extensive unit tests?

The Proof Is in the Code
The following source snippets, which include comments that I could only laugh at, illustrate my points.

I found the first one in JDK 1.3.1 in the java.awt.color.ColorSpace.getName(int) method. It contained the classic computer-programmer-under-pressure comment of "REMIND - ...":

From JDK 1.3.1: java.awt.color.ColorSpace:

    /**
     * Returns the name of the component given the component index
     */
    public String getName (int idx) {
        /* REMIND - handle common cases here */
        return new String("Unnamed color component("+idx+")");
    }

I went back to JDK 1.2.2 and found exactly the same comment (I didn't have source to earlier versions on my disk). I immediately opened up the source for JDK 1.4 beta, and chuckled even more when I saw this:

From JDK 1.4 beta: java.awt.color.ColorSpace:

    /**
     * Returns the name of the component given the component index.
     * @param idx The component index.
     * @return The name of the component at the specified index.
     */
    public String getName (int idx) {
        /* REMIND - handle common cases here */
        return new String("Unnamed color component("+idx+")");
    }

Wow, so that's what idx meant! I thought it was an abbreviation of "idiots do XML." Oh, and getName() returns a name! Who would've guessed? Why didn't they spend more time fixing the code instead of writing pointless comments?

Another one that had me chortling is java.util.Locale.toLowerCase(), which had this magical reminder: "Look at optimizations later."

From JDK 1.3.1: java.util.Locale:

    /*
     * Locale needs its own, locale-insensitive version of toLowerCase to
     * avoid circularity problems between Locale and String.
     * The most straightforward algorithm is used. Look at optimizations later.
     */
    private String toLowerCase(String str) {
        char[] buf = str.toCharArray();
        for (int i = 0; i < buf.length; i++) {
            buf[i] = Character.toLowerCase( buf[i] );
        }
        return new String( buf );
    }

Sure, this is inefficient, but isn't the whole Locale class? Even hashCode is synchronized—generally not a good idea at all. Why didn't the programmers simply optimize it in the first place?

When Comments Work
So, which comments do I like? I like comments that provide information I could not glean from the name of the method, such as pre/post conditions. Comments are absolutely essential with interfaces, because I cannot guess what the message would really do unless it had a good comment.

Editor's note: This article first appeared in Dr. Kabutz's "The Java Specialists' Newsletter" under the title Why I don't read your code comments .... To subscribe, send an email to join-thejavaspecialists@burst.sparklist.com.