Java Comments

A recipe says "add 2 cups of rice", but a good one also says "wash the rice first, or it turns sticky". The extra note isn't an instruction you cook; it explains why. In Java, those notes are comments: text the compiler completely ignores, written for the next person who reads your code. Very often, that person is you, six months later.

Three Kinds of Comments

All Three in One Program

/**
 * Works out GST on a price. GST is a tax added to the price
 * of most goods and services in India.
 */
public class Gst {
    // GST rate in percent; 18 is the rate for most services
    static final int RATE = 18;
 
    /*
     * Integer division drops the decimal part, so
     * Rs. 99 gives Rs. 17, not Rs. 17.82.
     */
    static int gst(int price) {
        return price * RATE / 100;
    }
 
    public static void main(String[] args) {
        System.out.println("GST on Rs. 500: Rs. " + gst(500)); // 90
        System.out.println("GST on Rs. 99: Rs. " + gst(99));
    }
}

GST on Rs. 500: Rs. 90
GST on Rs. 99: Rs. 17

How it works

1. Lines 1 to 4 are a documentation comment describing the class.
2. Line 6 is a single-line comment explaining why the number is 18.
3. Lines 9 to 12 are a multi-line comment warning about integer division.
4. On line 18, a single-line comment sits at the end of a line of code. Everything after // is ignored.
5. None of the comments change the output. The compiler throws them away before creating bytecode.

Try it yourself: put // in front of line 19 and run it again. What happens to the second line of output?

Documentation Comments and javadoc

The JDK's javadoc tool reads /** ... */ comments and builds HTML pages, like the official Java API documentation. Special tags starting with @ describe parts of a method:

/**
 * Works out the total fare for a group.
 *
 * @param farePerPerson the fare for one passenger, in rupees
 * @param passengers    how many people are traveling
 * @return the total fare in rupees
 */
static int totalFare(int farePerPerson, int passengers) {
    return farePerPerson * passengers;
}

Running javadoc -d docs Fare.java creates a docs folder with an index.html you can open in a browser. IDEs also show these comments when you hover over a method name.

From Java 23, documentation comments can also be written in Markdown, with /// at the start of each line instead of /** */. Most existing code still uses the /** */ form, so learn that one first.

What Makes a Good Comment

A good comment explains why: a business rule, a surprising decision or a known trap. The code itself should say what it does, through clear names.

Common Mistakes

Nesting multi-line comments. /* outer /* inner */ still outer? */ doesn't work: the first */ ends the comment, and the rest becomes a compile error.

Leaving big blocks of commented-out code. Version control (Git) remembers old code. Delete it instead of hiding it.

Using /** for ordinary notes inside a method. Documentation comments belong above classes, methods and fields, where javadoc looks for them.

Practice

1. Easy: Add a documentation comment to the gst method in Gst.java, with @param and @return tags.
2. Harder: Find a comment in any program you've written that just repeats the code. Rename a variable or method so the comment isn't needed, then delete it.

Key Takeaways