Using the Right Comment in Java

Java provides three types of comments:

  • Multi-Line (C-Style) Comments

Java also provides a comment type that can span multiple lines. You start this type of comment with a forward slash followed by an asterisk, and end it with an asterisk followed by a forward slash. The start and end delimiters for this type of comment may be on the same line, or they can be on different lines. For example

Figure 2: Multi-line comments

/* This is a c-style comment */

/*  This is also a

    c-style comment, spanning

    multiple lines */

Note that C-style comments cannot be nested. Something like

will generated a syntax error because the java compiler will only treat through the first */ as a comment. (The comment ends at the first "*/" the compiler sees.)

You can nest single-line comments within multi-line comments:

Figure 4: Good comment nesting

/* This is a single-line comment:

    // a single-line comment

 */

and multi-line comments in single-line comments:

Figure 5: Multi-line comments in a single-line comment

// /* this is

//    a multi-line

//    comment */

When to Use Documentation Comments

Documentation comments should (at very least) be used in front of every public class, interface, method and class/instance variable in your source code. This allows someone to run javadoc against the code and generate a simple document that lists the public entities and a brief description of each. You may also use documentation comments in front on non-public methods, and use a javadoc option to generate documentation for them. Using documentation comments on non-public entities is not as important as publics (the interface isn't exposed...) but if you're commenting the code anyway you might as well write those comments as documentation comments.

When to Use Single-Line Comments

Always!

My simple advice on commenting is that whenever you want to write a normal comment (not a documentation comment that describes and class, interface, method or variable) use a single line comment.

Why? Because you can easily use multi-line comments to "comment out" a section of your code! ("Commenting out code" refers to changing the lexical state of a section of source code to being inside a comment, making the compiler ignore that code.) Take as an example:

Figure 10: Code to comment out

x = 1;   /* set x to 1 */

y = 2;   /* set y to 2 */

f(x, y); /* call f with x and y */

If you want to comment out these three lines, you would either need to put a single line comment in front of each line:

Figure 11: Commenting-out code using single-line comments

// x = 1;   /* set x to 1 */

// y = 2;   /* set y to 2 */

// f(x, y); /* call f with x and y */

or add in multi-line comments wherever there isn't already one present:

Figure 12: Commenting-out code using multi-line comments

/* x = 1;  */ /* set x to 1 */

/* y = 2;  */ /* set y to 2 */

/* f(x, y);*/ /* call f with x and y */

or mutilate/remove the "end comment" delimiters of the existing comments:

Figure 13: Commenting-out code using multi-line comments (alternative)

/*

x = 1;   /* set x to 1 * /

y = 2;   /* set y to 2 * /

f(x, y); /* call f with x and y * /

*/

None of these are terribly pleasant. It's much easier if the original code were:

Figure 14: Easier code to comment out

x = 1;   // set x to 1

y = 2;   // set y to 2

f(x, y); // call f with x and y

then you can easily comment it out by just placing a multi-line comment around it:

Figure 15: Commenting-out single-line comments with a single multi-line comment

/*

x = 1;   // set x to 1

y = 2;   // set y to 2

f(x, y); // call f with x and y

*/

Always use single-line comments for your everyday commenting needs!

When to Use Multi-Line Comments

After reading the above section, this becomes obvious. Only use multi-line comments to comment out sections of code. Never use them for any other purpose!