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

A comment is text the compiler ignores. Comments are written for people: to explain why code does something, to document how to use a method, or to leave a note for later.

Single-line comments: //#

Everything after // on that line is a comment:

public class Main {
    public static void main(String[] args) {
        // Print a welcome message
        System.out.println("Welcome!");

        int seats = 40;  // the hall has 40 seats
        System.out.println(seats + " seats");
    }
}

Welcome!
40 seats

Multi-line comments: /* */#

Text between /* and */ is a comment, even across several lines. Multi-line comments cannot be nested: the first */ ends the comment.

public class Main {
    public static void main(String[] args) {
        /*
           Ticket price rules:
           - children under 12 pay half
           - everyone else pays full price
        */
        int fullPrice = 200;
        System.out.println(fullPrice / 2);
    }
}

100

Javadoc comments: /** */#

A comment that starts with /** and sits directly above a class, method or field is a Javadoc comment. The javadoc tool (and every Java IDE) turns these into documentation; hovering over a method in your editor shows it. Tags such as @param and @return describe the parameters and the result:

public class Geometry {
    /**
     * Returns the area of a rectangle.
     *
     * @param width  the width, in metres
     * @param height the height, in metres
     * @return the area, in square metres
     */
    static double area(double width, double height) {
        return width * height;
    }

    public static void main(String[] args) {
        System.out.println(area(4.5, 2));
    }
}

9.0

Notice 9.0: Java always prints a double with a decimal part. Public classes and methods in libraries are expected to have Javadoc comments.

Commenting out code#

While testing, you can disable a line by turning it into a comment:

public class Main {
    public static void main(String[] args) {
        System.out.println("Step 1");
        // System.out.println("Step 2");
        System.out.println("Step 3");
    }
}

Step 1
Step 3

Most editors toggle comments with Ctrl + / (Cmd + / on macOS). Delete commented-out code before sharing it; version control keeps the history.

Writing good comments#

Explain why, not what:

// Bad: repeats the code
count = count + 1; // add one to count

// Good: explains the reason
count = count + 1; // include the header row in the total

Good comments document decisions, business rules and surprising behaviour, and mark unfinished work with a searchable tag such as // TODO: handle negative amounts. If code needs a comment to explain what it does, first try clearer names.

Common mistakes#

Practice#

static int square(int n) {
    return n * n;
}

public class Main {
    /**
     * Returns the square of a number.
     *
     * @param n the number to square
     * @return n multiplied by itself
     */
    static int square(int n) {
        return n * n;
    }

    public static void main(String[] args) {
        System.out.println(square(5));
    }
}

25

Key takeaway#