Java comments

›Short versionOpen if you only have a minute.

A comment is text the compiler discards. It does not run, and it is not an instruction in the class file.
// ignores the rest of one line. /* ignores everything until the next */.
Block comments do not nest. The first */ closes the comment, and the text after it is code again.
Characters inside quotes are never a comment. // in a URL is part of the string.
A comment that describes a different decision from the code is the one that causes the next bug.

A is a note to the next reader, who is often you. The sees the marks, skips the note, and compiles only what is left. That is also how you set a line aside while you test the lines around it.

java

// This is a single-line comment
System.out.println("Hello World");

int age = 25; // the value stored for this run

// System.out.println("This won't run!");

A starts at // and ends when the line ends. The declaration of age still runs. The print that sits after // does not. The sentence after the semicolon is not executed either. It is not part of the statement.

A region, and where it actually ends

A starts at /* and runs until the next */. Use it when the note, or the code you are holding back, covers more than one line.

java

/* This is a multi-line comment.
   It can span multiple lines. */
System.out.println("Hello World");

/*
System.out.println("Line 1");
System.out.println("Line 2");
System.out.println("Line 3");
*/

Only the Hello World line runs. The three prints between the second pair of marks are not in the program the compiler writes. The failure comes when a second comment opens before the first one closes.

java

/* outer
   /* inner */
   System.out.println("still compiled");
*/

Notes the documentation tool keeps

A comment is a block comment whose opening mark is /**. Place it immediately above the class or method it describes. The compiler still throws it away as code. The javadoc tool reads the tags and writes the HTML other programmers look up.

java

/**
 * Adds two integers and returns the sum.
 *
 * @param a the first integer
 * @param b the second integer
 * @return the sum of a and b
 */
public int add(int a, int b) {
    return a + b;
}

Write the comment for the decision a reader cannot see. double tax = price * 0.15; already says that a price is multiplied by 0.15. A useful line above it says that 0.15 is the rate for an international order. When the rate changes, the comment has to change with it. A stale comment is ordinary text the compiler will never correct.

// TODO and // FIXME are conventions, not language. Editors collect them into a list. The program does not treat them as unfinished work.

java

System.out.println("Hello");
// System.out.println("World");
/* System.out.println("Java"); */
System.out.println("Programming");

What does that program print?

Hello, then Programming, each on its own line. The World line is a line comment. The Java line sits inside a block comment. Neither call is compiled. The words in quotes would have been printed only if those lines had been code.