Comments (// and /* */ and /** */)

// Single-line comment — everything from // to the end of the line is a comment.
int x = 10; // Inline comment — can also be written after code.

/*
  Block comment — everything between /* and */ is a comment.
  Use this when you want to write a comment that spans multiple lines. Cannot be nested.
*/

/**
 * Javadoc comment — a block comment that starts with /**.
 * Written immediately before a class, method, or field.
 * The javadoc tool generates HTML documentation from these comments.
 *
 * @param paramName Description of the parameter
 * @return Description of the return value
 * @throws ExceptionClass Conditions under which the exception is thrown
 */

Javadoc comments use block tags starting with @ to structure information. IDEs such as IntelliJ IDEA and Eclipse read Javadoc and display it in code completion and hover tooltips.

Run the javadoc command to generate HTML documentation.

javadoc -d doc -sourcepath src -subpackages com.example

CommentBasic.java

// CommentBasic.java — Basic usage of Java comment syntax.

public class CommentBasic {

    /* Define the number of items as a constant */
    private static final int ITEM_COUNT = 3;

    public static void main(String[] args) {
        // Define arrays of item names and prices
        String[] items = {"widget", "gadget", "device"};
        int[]    prices = {1200, 3500, 800}; // Prices before tax

        int total = 0;

        for (int i = 0; i < ITEM_COUNT; i++) {
            System.out.printf("%-10s %5d yen%n", items[i], prices[i]);
            total += prices[i];
        }

        System.out.println("----------");
        System.out.printf("%-10s %5d yen%n", "Total", total);
    }
}

The following example shows how this works in practice:

$ javac CommentBasic.java && java CommentBasic
widget      1200 yen
gadget      3500 yen
device       800 yen
----------
Total       5500 yen

Calculator.java

/**
 * Utility class for numeric calculations.
 *
 * 
Provides basic statistical calculation methods for integer arrays.
 *
 * @author example
 * @since 1.0
 */
public class Calculator {

    /**
     * Computes the sum of an integer array and returns it.
     *
     * @param values The integer array to sum
     * @return The sum of all elements
     * @throws IllegalArgumentException if values is null
     */
    public static int sum(int[] values) {
        if (values == null) {
            // null is not supported — throw an exception
            throw new IllegalArgumentException("values must not be null");
        }

        int total = 0;
        for (int v : values) {
            total += v;
        }
        return total;
    }

    /**
     * Computes the average of an integer array and returns it.
     *
     * 
Returns {@code 0.0} if the array is empty.
     *
     * @param values The integer array to average
     * @return The average as a double. Returns 0.0 if the array is empty.
     * @throws IllegalArgumentException if values is null
     * @see #sum(int[])
     */
    public static double average(int[] values) {
        if (values == null) {
            throw new IllegalArgumentException("values must not be null");
        }
        if (values.length == 0) {
            return 0.0; /* Guard against division by zero */
        }

        /* Cast to avoid integer division */
        return (double) sum(values) / values.length;
    }

    /**
     * @deprecated Use {@link #average(int[])} instead.
     */
    @Deprecated
    public static double mean(int[] values) {
        return average(values);
    }

    public static void main(String[] args) {
        int[] scores = {85, 92, 78, 95, 60};

        System.out.println("Sum:     " + sum(scores));
        System.out.printf("Average: %.1f%n", average(scores));
    }
}

The following example shows how this works in practice:

$ javac Calculator.java && java Calculator
Sum:     410
Average: 82.0

Java has three comment types: single-line comments (//), block comments (/* */), and Javadoc comments (block comments starting with /**). Single-line comments are used for short notes and commenting out a single line. Block comments are used for multi-line explanations. Note that block comments cannot be nested.

The convention is to write Javadoc comments immediately before public classes, methods, and fields. Tags such as @param, @return, @throws, @deprecated, and @see structure the documentation so the javadoc tool can generate HTML automatically. The official JDK API documentation is itself written in this format. IDEs such as IntelliJ IDEA and Eclipse read Javadoc and display it on hover and in code completion, making it worthwhile to add documentation comments to all public APIs.