Java Comments

Comments are text the compiler ignores. They exist for the humans reading the source. Java has three kinds — single-line, multi-line, and Javadoc — each with its own role.

Single-line comments — //

Everything from // to the end of the line is a comment:

int total = price * quantity;   // running subtotal in cents
// totalPrice was renamed to total in 2024-05

Use these for short notes alongside a line of code, or to temporarily disable a line during debugging.

Multi-line comments — /* ... */

Anything between /* and */ is ignored, even across multiple lines:

/*
 * The default leading-asterisk style isn't required, but most IDEs
 * insert it automatically and it keeps long comments readable.
 *
 * This block is parsed as a single comment.
 */
int retries = 3;

Multi-line comments can also appear inline:

int width = 800 /* pixels */;

You cannot nest them: /* outer /* inner */ */ ends at the first */, leaving stray */ characters that fail to compile. To "comment out" a block that already contains /* … */, use // on each line (your IDE has a shortcut for it — typically Ctrl+/ / Cmd+/).

Javadoc comments — /** ... */

Javadoc comments start with /** (note: two stars) and are read by the javadoc tool to generate HTML documentation:

/**
 * Calculates the area of a rectangle.
 *
 * @param width  the rectangle's width in cm; must be non-negative
 * @param height the rectangle's height in cm; must be non-negative
 * @return the area in square centimeters
 */
public static double area(double width, double height) {
    return width * height;
}

Javadoc comments are placed immediately above the class, method, or field they describe. The first sentence becomes the summary line in the generated docs.

The most useful tags:

• @param name description — one per parameter
• @return description — what the method returns
• @throws ExceptionClass description — when the method throws
• @see ClassOrLink — cross-reference
• @since 1.5 — when this API was added
• @deprecated reason — discourages further use (the compiler also warns)

The whole standard library is documented with Javadoc; IDEs read it to power their tooltips.

When to comment, when not to

Good code is its own documentation. Comments that restate what the code already shows just add noise and rot quickly:

// BAD: increment counter
counter++;

// BAD: returns the user's name
public String getName() { return name; }

Comments earn their place when they explain why, not what:

// Stripe rejects amounts smaller than $0.50 — round up so we never
// hit the minimum-charge error.
int chargeCents = Math.max(50, computed);

Or when they document a non-obvious constraint:

// Caller must hold the writeLock; this method itself does no locking.
private void persist(Order o) { ... }

For public APIs, write Javadoc. For internal code, write only the comments that help the next reader make a decision.

A demonstration

The compiler strips all three comment styles before generating bytecode, so they have zero runtime cost.

What's next

Java Variables introduces variable declaration, initialization, and scope.

Practice