Comments in Java

Learn the three types of Java comments and when to use each one to make your code more readable.

Overview

Comments are text in your code that the Java compiler completely ignores. They exist only for humans - to explain what the code does, why a decision was made, or to temporarily disable code while debugging. Good comments make code much easier to understand and maintain. Java has three comment styles: single-line comments (//), multi-line block comments (/* ... */), and Javadoc comments (/** ... */) used to auto-generate documentation. You will use single-line comments most often while learning.

Key Points

•// starts a single-line comment - everything after // on that line is ignored by the compiler
•/* ... */ is a block comment - can span multiple lines; used for longer explanations
•/** ... */ is a Javadoc comment - placed before classes and methods to generate API documentation
•Comments are removed before compilation and have zero effect on program performance
•Over-commenting is as bad as under-commenting - comment the WHY, not the obvious WHAT
•Temporarily commenting out code during debugging is a common and valid use

Examples

Single-line comments

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

        int age = 25; // must be 18 or older to proceed

        // TODO: add input validation here
    }
}

// is the most common comment. Use it for short, one-line explanations.

Multi-line block comments

/*
 * This program calculates compound interest.
 * Formula: A = P(1 + r/n)^(nt)
 * P = principal, r = annual rate, n = compounds per year, t = years
 */
public class CompoundInterest {
    public static void main(String[] args) {
        /* temporarily disabled:
        double result = calculate(1000, 0.05, 12, 5);
        System.out.println(result);
        */
    }
}

Block comments are useful for explaining complex logic or temporarily disabling multiple lines.

Javadoc comments - auto-generate documentation

/**
 * Calculates the area of a rectangle.
 *
 * @param width  the width of the rectangle in centimetres
 * @param height the height of the rectangle in centimetres
 * @return the area in square centimetres
 */
public static double rectangleArea(double width, double height) {
    return width * height;
}

Run `javadoc MyClass.java` to generate HTML documentation from these comments.

Common Mistakes

Commenting the obvious: `i++; // increment i by 1` adds no value - skip it
Leaving outdated comments that describe what the code used to do, not what it does now
Using block comment /* */ inside another block comment - Java does not support nested block comments

Note

In IntelliJ IDEA or VS Code, press Ctrl+/ (Cmd+/ on Mac) to toggle a single-line comment on the current line. Select multiple lines and press Ctrl+/ to comment them all at once.

Comments in Java

Overview

Key Points

Examples

Common Mistakes

Note

Exercises

Knowledge Check

Which comment type is used to generate HTML documentation with the javadoc tool?