Using the Right Comment in Java

Java provides three types of comments:

• Single-Line (C++-Style) Comments

  The simplest comment in Java is the single line comment. It starts with two forward slashes and continues to the end of the line. For example:

  Figure 1: Single-line comments

  // this is a single-line comment
  x = 1; // a single-line comment after code

• 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

Figure 3: Bad comment nesting

/* A comment looks like
   /* This is a comment */
   blah blah blah
 */

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

• Documentation Comments

  Documentation comments are special comments that look like multi-line comments but can be used to generate external documentation about your source code. These begin with a forward slash followed by two asterisks, and end with an asterisk followed by a forward slash. For example:

  Figure 6: Documentation comment

  /** This is a documentation comment */
  /** This is also a
      documentation comment */

  There are a few important things to note about documentation comments:

• The documentation generator, javadoc, will add all text inside a documentation comment to an HTML paragraph. This means that any text inside a documentation comment will be formatted into a paragraph; spacing and line breaks are ignored. If you want special formatting, you must include HTML tags inside your documentation comment.
• • If a documentation comment begins with more than two asterisks, javadoc assumes this is just used to create a "box" around the comment in the source code and ignores the extra asterisks. For example:

    Figure 7: Extra asterisks

    /**********************************
       This is the start of a method
    **********************************/

    will only keep the text "This is the start of a method".

  • javadoc will ignore leading asterisks inside a documentation-comment block. For example:

    Figure 8: Leading asterisks

    /***************************************
     * This is a doc comment
     * on multiple lines that I want to stand
     * out in source code, looking "neat"
     ***************************************/

    will only keep the text "This is a doc comment on multiple lines that I want to stand out in source code, looking "neat""

  • It's common practice to use something like

    Figure 9: Accidental javadoc comment

    /******************************************
       ...
     ******************************************/

    to make a comment stand out. Be aware that this is treated as a documentation comment (even if that's not what you had intended), and could show up in the generated documentation.

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. Neveruse them for any other purpose!