Java Comments

Comments are notes in source code that the compiler ignores. They exist purely to communicate intent, context, and reasoning to human readers — including your future self. Java supports three comment styles.

Why it matters

Code is read far more often than it is written, usually by someone who was not there when the decision was made. A good comment records the reason that cannot be seen in the code; a bad one repeats the code and then goes out of date. Javadoc comments also become the documentation other developers see in their editor when they call your method.

Single-line, Multi-line, and Javadoc Comments

A single-line comment starts with // and continues to the end of the line. A multi-line (block) comment is wrapped between /* and */ and can span multiple lines. A Javadoc comment starts with /** and is used to generate HTML API documentation with the javadoc tool; it supports tags like @param, @return, and @throws.

What Makes a Good Comment

Professional Java code favors comments that explain "why," not "what" — good naming already communicates what code does. A comment should capture a non-obvious constraint, a workaround for a specific bug, or a business rule that isn't visible from the code itself. Comments that just restate the code in English go stale and mislead readers when the code changes but the comment doesn't.

Example

public class CommentsDemo {

    // Discount is capped at 50% per company policy, not a technical limit.
    static final double MAX_DISCOUNT = 0.50;

    /*
     * This method is intentionally simple: pricing rules are being
     * redesigned next quarter, so no extra abstraction is added yet.
     */
    static double applyDiscount(double price, double discount) {
        double capped = Math.min(discount, MAX_DISCOUNT);
        return price - (price * capped);
    }

    /**
     * Prints the final price after applying a capped discount.
     *
     * @param price original price before discount
     * @param discount requested discount as a fraction (0.0 to 1.0)
     */
    public static void main(String[] args) {
        double price = 100.0;
        double discount = 0.75; // requested above the cap, will be limited
        System.out.println(applyDiscount(price, discount));
    }
}

50.0

Exercise

Document the method below with a Javadoc comment. It should have a one-sentence description, a @param tag for each parameter and a @return tag. The program's behaviour does not change.

Expected output: 9

public class MathUtil {

    // TODO: replace this line with a Javadoc comment
    static int max(int a, int b) {
        return a > b ? a : b;
    }

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

public class MathUtil {

    /**
     * Returns the larger of two integers.
     *
     * @param a the first value
     * @param b the second value
     * @return the greater of a and b; either one if they are equal
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

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

Quick quiz