Comments in Java

Why are comments used in Java?

Comments communicate information that is useful to a person reading the code. A good comment explains intent, a non-obvious decision, an assumption, or the public contract of an API.

• Explain why a particular approach was chosen.
• Describe complex logic or an important constraint.
• Document public classes, methods, parameters, return values, and exceptions.
• Leave focused maintenance notes when appropriate.

Types of comments in Java

Single-line comments

A single-line comment begins with //. Everything from // to the end of that line is comment text.

// This program displays a greeting
public class SingleLineComment {
    public static void main(String[] args) {
        System.out.println("Hello World"); // Print the message
    }
}

Output

Hello World

The first comment occupies a complete line. The second comment follows a statement and explains that statement. Both forms use the same // syntax.

Multi-line comments

A multi-line comment begins with /* and ends with */. The comment can occupy one line or span several lines.

/*
 * This program demonstrates
 * a comment that spans multiple lines.
 */
public class MultiLineComment {
    public static void main(String[] args) {
        System.out.println("Multi-line comment example");
    }
}

Documentation comments (Javadoc)

A documentation comment begins with /** and ends with */. The javadoc tool reads these comments to generate browsable API documentation.

/**
 * Provides basic arithmetic operations.
 *
 * @author ProwessApps
 * @version 1.0
 */
public class Calculator {

    /**
     * Adds two integer values.
     *
     * @param first the first value
     * @param second the second value
     * @return the sum of first and second
     */
    public int add(int first, int second) {
        return first + second;
    }
}

Common Javadoc tags

Generate API documentation

After saving the example as Calculator.java, run:

javadoc -d docs Calculator.java

The -d docs option places the generated documentation in a folder named docs. Open the generated index.html file in a browser.

Comment best practices

• Explain intent and important decisions rather than translating each line into English.
• Keep comments accurate when the surrounding code changes.
• Use clear names first, then add comments where context is still needed.
• Keep comments concise and close to the code they describe.
• Use Javadoc for public APIs that other developers need to understand.
• Avoid placing passwords, tokens, private data, or confidential information in comments.

// Add 1 to count
count++;

// Record the successful retry.
count++;

Common mistakes with Java comments