Comments in Java – Single-line, Multi-line and Javadoc

Comments are notes in your source code that the compiler ignores. They explain why code exists, warn about tricky parts, and, in the case of Javadoc comments, become the official documentation of your classes and methods.

Java has three kinds of comments: single-line, multi-line and documentation (Javadoc) comments. This tutorial shows each one, the most useful Javadoc tags, how to generate HTML documentation, and how to write comments that actually help.

1. The Three Types of Comments

/**
 * Demonstrates the three kinds of comments in Java.
 */
public class CommentTypes {

    public static void main(String[] args) {
        // Single-line comment: everything after // is ignored
        int width = 8;   // comments can also follow code on the same line

        /*
         * Multi-line comment: useful for longer explanations
         * that span several lines.
         */
        int height = 5;

        int area = width * height /* inline block comment */ ;
        System.out.println("Area: " + area);

        // System.out.println("This line is commented out and will not run");
    }
}

Area: 40

The commented-out println did not run, and the block comment in the middle of the expression was simply ignored.

2. Single-Line Comments

A single-line comment starts with // and runs to the end of the line. It is the most common kind of comment:

// Retry three times because the payment gateway sometimes times out
int maxRetries = 3;

double total = price * quantity; // tax is added later in checkout()

3. Multi-Line Comments

A multi-line comment starts with /* and ends with */. Everything between, across any number of lines, is ignored. The leading * on each line is only a style convention.

/*
 * Prices are stored in paise (1 rupee = 100 paise) to avoid
 * floating-point rounding errors. Convert to rupees only
 * when displaying values to the user.
 */
long priceInPaise = 49_950;

4. Documentation Comments (Javadoc)

A Javadoc comment starts with /** and is placed directly before a class, interface, constructor, method or field. The javadoc tool turns these comments into HTML pages, the same format as the official Java API documentation, and IDEs show them as tooltips.

/**
 * A simple calculator for basic arithmetic.
 *
 * <p>All methods are static, so no object is needed:
 * {@code Calculator.divide(10, 2)}.</p>
 *
 * @author JavaByTechie
 * @since 1.0
 */
public class Calculator {

    /**
     * Divides one integer by another.
     *
     * @param dividend the number to divide
     * @param divisor  the number to divide by; must not be zero
     * @return the whole-number quotient
     * @throws ArithmeticException if {@code divisor} is zero
     * @see Math#floorDiv(int, int)
     */
    public static int divide(int dividend, int divisor) {
        if (divisor == 0) {
            throw new ArithmeticException("divisor must not be zero");
        }
        return dividend / divisor;
    }

    public static void main(String[] args) {
        System.out.println("17 / 5 = " + divide(17, 5));
    }
}

17 / 5 = 3

The first sentence becomes the summary shown in method lists, so make it a complete, clear description.

5. Common Javadoc Tags

6. Generating HTML Documentation

The JDK's javadoc tool reads your source files and produces a set of HTML pages:

javadoc -d docs Calculator.java     # writes docs/index.html, docs/Calculator.html ...

# With Maven
mvn javadoc:javadoc

Javadoc warns about public elements that have no comment, which helps you keep a library's API fully documented. Java 23 also added support for writing Javadoc in Markdown using /// comments.

7. A Surprising Detail: Unicode Escapes in Comments

The compiler translates Unicode escapes such as \u000d (carriage return) before it removes comments. A line break hidden in a comment therefore ends the comment early, and the rest of the line is compiled as code:

public class UnicodeInComment {
    public static void main(String[] args) {
        // Unicode escapes are processed BEFORE comments are removed.
        // \u000d System.out.println("Surprise: this line runs!");
        System.out.println("Done");
    }
}

Surprise: this line runs!
Done

This is a popular interview puzzle. In real code, never put Unicode escapes for line breaks, quotes or backslashes in comments.

8. Writing Good Comments

• Explain why, not what. The code already shows what happens; the comment should give the reason, the business rule or the trade-off.
• Prefer clear names over comments. int daysUntilExpiry needs no comment; int d; // days until expiry does.
• Document public APIs with Javadoc: purpose, parameters, return value, exceptions and edge cases.
• Keep comments up to date. A wrong comment is worse than none.
• Do not leave dead code commented out; version control remembers old code for you.
• Use TODO and FIXME markers sparingly and with context; IDEs list them for you.

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

// Good: explains the reason
attempts++; // the API counts the first call as attempt 1, so start reporting from 1

9. Do Comments Affect Performance?

No. The compiler discards comments, so they never reach the .class file and have no effect on speed or size at runtime. Javadoc comments are only read by the javadoc tool and IDEs.

10. Summary

• Java has single-line (//), multi-line (/* */) and documentation (/** */) comments.
• Block comments cannot be nested.
• Javadoc comments with tags such as @param and @return generate HTML API documentation.
• Comments do not affect the compiled program.
• Good comments explain intent and stay accurate; clear code needs fewer comments.

Related Tutorials

• How to Write a Java Program
• Methods in Java
• Keywords in Java

Reference: Oracle: Javadoc Guide

Frequently Asked Questions (FAQ)