Java Comments: Single-Line, Multi-Line, and Javadoc

What Comments Are For

A comment is text in your source code that the Java compiler ignores completely. It never becomes part of the running program - it exists purely for humans reading the code. You use comments to explain why something is done a certain way, to leave reminders, or to temporarily disable code without deleting it.

Java has three kinds of comments: single-line (//), multi-line block comments (/* */), and Javadoc documentation comments (/** */). They all do the same basic job - get ignored at compile time - but you reach for each in different situations.

Single-Line Comments

Two forward slashes (//) start a comment that runs to the end of the current line. The compiler skips everything from the // to the line break.

public class Main {
    public static void main(String[] args) {
        // Print a greeting to the console
        System.out.println("Hello, Java!");

        int score = 90; // a comment can also sit after code
        System.out.println(score);
    }
}

Notice the second comment shares a line with real code. Everything before // still runs; only the part after it is ignored. This is the most common comment style for short notes.

Multi-Line Block Comments

When your note spans several lines, a block comment is cleaner than prefixing every line with //. A block comment starts with /* and ends with */. Everything between the two - however many lines - is ignored.

public class Main {
    public static void main(String[] args) {
        /*
         * This program shows a block comment.
         * The leading asterisks on each line are just a
         * convention for readability - they are not required.
         */
        System.out.println("Block comments are handy.");
    }
}

The aligned * characters down the left edge are a style convention, not a rule. The only parts that actually matter are the opening /* and the closing */.

Commenting Out Code

Comments are the standard way to disable code while you experiment, without deleting it. Use // for a single line, or a block comment to switch off several lines at once.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

Run it and you will see only the two "runs" lines print. The commented-out println calls are invisible to the compiler.

A common gotcha: block comments do not nest. The first */ closes the comment, no matter how many /* came before it. So you cannot wrap a /* ... */ block inside another /* ... */ block - the inner */ ends the whole thing and the rest becomes a syntax error. If you need to disable a region that already contains block comments, use // on each line instead (most editors do this with a single keyboard shortcut).

Javadoc Documentation Comments

A Javadoc comment looks like a block comment but starts with /** - two asterisks. It is meant to document a class, method, or field, and it sits directly above the thing it describes. The javadoc tool turns these into browsable HTML API docs, and IDEs display them as hover tooltips.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

The @param, @return, and @throws tags are structured fields the tooling understands. To the compiler this is still just an ignored comment - the value is entirely in the documentation it produces and the IDE hints it gives other developers (and you, six months later).

Good Comments vs. Noise

A comment should explain something the code cannot say on its own. Comments that merely restate the code add clutter and tend to drift out of date as the code changes.

// Bad: just repeats what the code obviously does
int i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

Aim to make the code readable through clear names and structure, and save comments for the why - intent, trade-offs, edge cases, and links to context. If you find yourself writing a comment to explain a confusing line, that is often a hint to rename a variable or extract a method instead.

Next: Variables

Now that you can annotate your code, the next building block is storing data in it. The next page covers variables - how to declare them, the types they hold, and the rules Java enforces because it is statically typed.