Comments, Javadoc and naming conventions

One line in this lesson looks like a comment and still changes a discount from 10 % to 50 %, because Java turns the six characters \u000a into a line break before it looks for comments at all. Comments are what the compiler skips and names are what a reader reads first, so both decide whether code says what it does. Java has three kinds of comments: // to the end of the line, /* … */ blocks, and documentation comments, which the javadoc tool turns into HTML pages.

You will step through how the compiler reads a block comment that seems to nest, document one class in both the HTML and the Markdown style, let doclint report what is missing, and name things the way the Java Language Specification recommends. A rule of thumb runs through all of it: let names say what the code does, and let comments say why.

Three kinds of comments, and block comments do not nest

An end-of-line comment starts with // and runs to the end of the line. A block comment runs from /* to the next */. A documentation commentdocumentation comment: A comment directly above a class, field, constructor or method that the javadoc tool turns into HTML: /** … */ in HTML with tags, or, from Java 23, consecutive /// lines in Markdown. The compiler ignores it like any comment. describes the class, method or field right below it, written either as /** … */ in HTML or, since Java 23, as lines that start with ///, in Markdown. The compiler ignores all three:

// An end-of-line comment: from the two slashes to the end of the line.

/* A block comment can run over
   several lines, and it ends at the first star and slash. */

/// A documentation comment, written in Markdown (Java 23 and later). The javadoc tool turns it into HTML.
void main() {
    int seats = 40;                       // a comment can follow code on the same line
    /* or sit inside a line */ seats = seats + 2;
    IO.println("seats: " + seats);
}

from session import run, version

# Comments.java runs; Nested.java does not even compile, because block comments do not nest.
version()
run("""
java Comments.java
java Nested.java
""", expect_failure=("java Nested.java",))

# openjdk version "25.0.4.1" LTS
$ java Comments.java
seats: 42
$ java Nested.java
Nested.java:6: error: not a statement
    */
     ^
Nested.java:6: error: illegal start of expression
    */
    ^
2 errors
error: compilation failed
[exit status 1]

• // comments end at the end of the line, so they can follow code on the same line.
• /* … */ comments can run over several lines or sit in the middle of one, and they end at the first */.
• /// … lines are comments to the compiler too. Only javadoc gives them a meaning, as the section on documentation shows.
• Inside a // comment, /* and */ mean nothing, and inside a block comment // means nothing. Inside a string literal neither starts a comment: "/* not a comment */" is just text.

Block comments do not nest. Nested.java tried to switch off a rule that already held a comment, and the compiler stopped at line 6. Step through how it read lines 3 to 6:

A Unicode escape can end a comment early

Before the compiler looks for comments at all, it replaces every Unicode escapeUnicode escape: A backslash, the letter u and four hexadecimal digits, such as \u000a, that stands for one character. The compiler replaces every one in a source file before it looks for comments, so \u000a in a comment is a real line break., \u followed by four hexadecimal digits, with the character it stands for. \u000a stands for a line break:

// A comment that runs: a Unicode escape for a line break ends the comment early.
void main() {
    int discount = 10;
    // Festival offer ends tonight \u000a discount = 50;
    IO.println("discount: " + discount + "%");
}

from session import run

# UnicodeTrap.java compiles without a warning, prints 50%, and grep finds the escape that did it.
run("""
javac -Xlint:all -d classes UnicodeTrap.java
java UnicodeTrap.java
grep -n 'u000a' UnicodeTrap.java
""")

$ javac -Xlint:all -d classes UnicodeTrap.java
$ java UnicodeTrap.java
discount: 50%
$ grep -n 'u000a' UnicodeTrap.java
4:    // Festival offer ends tonight \u000a discount = 50;

Step through what the compiler did with line 4:

\u000a became a real line break, the comment ended in the middle of line 4, and discount = 50; became a statement that ran, so the program printed discount: 50%. javac -Xlint:all, with every warning switched on, said nothing. \u000d, a carriage return, ends a comment in the same way.

A documentation comment documents the declaration right below it

A documentation comment goes directly above what it describes: a class, an interface, a field, a constructor or a method. The javadoc tool turns these comments into the same kind of HTML pages as the JDK’s own API documentation:

The same class, documented in both styles:

/// Fee calculations for a coaching institute.
///
/// Every amount is a whole number of paise, so that no rounding error can build up.
public final class Fees {
    private Fees() {}

    /// Returns the fee after a percentage discount.
    ///
    /// The discount is rounded down to a whole paisa, so a student never pays less than the advertised rate. For
    /// example, `discounted(150_000, 10)` returns `135_000`.
    ///
    /// @param fee     the full fee in paise; must not be negative
    /// @param percent the discount, from 0 to 100
    /// @return the fee after the discount, in paise
    /// @throws IllegalArgumentException if `fee` is negative or `percent` is outside 0 to 100
    public static long discounted(long fee, int percent) {
        if (fee < 0 || percent < 0 || percent > 100) {
            throw new IllegalArgumentException("fee " + fee + ", percent " + percent);
        }
        return fee - fee * percent / 100;
    }
}

/**
 * Fee calculations for a coaching institute.
 * <p>
 * Every amount is a whole number of paise, so that no rounding error can build up.
 */
public final class Fees {
    private Fees() {}

    /**
     * Returns the fee after a percentage discount.
     * <p>
     * The discount is rounded down to a whole paisa, so a student never pays less than the advertised rate. For
     * example, {@code discounted(150_000, 10)} returns {@code 135_000}.
     *
     * @param fee     the full fee in paise; must not be negative
     * @param percent the discount, from 0 to 100
     * @return the fee after the discount, in paise
     * @throws IllegalArgumentException if {@code fee} is negative or {@code percent} is outside 0 to 100
     */
    public static long discounted(long fee, int percent) {
        if (fee < 0 || percent < 0 || percent > 100) {
            throw new IllegalArgumentException("fee " + fee + ", percent " + percent);
        }
        return fee - fee * percent / 100;
    }
}

from session import run

# javadoc checks both versions of Fees.java and writes their HTML; sed prints the part about discounted() from the
# Markdown version's page, then grep the description of discounted() from the classic version's page.
run("""
javadoc -quiet -notimestamp -Xdoclint:all -d docs markdown/Fees.java
javadoc -quiet -notimestamp -Xdoclint:all -d docs-classic classic/Fees.java
sed -n '/<section class="detail" id="discounted/,/<[/]section>/p' docs/Fees.html
sed -n '/<section class="detail" id="discounted/,/<[/]section>/p' docs-classic/Fees.html | grep -A3 'class="block"'
""")

$ javadoc -quiet -notimestamp -Xdoclint:all -d docs markdown/Fees.java
$ javadoc -quiet -notimestamp -Xdoclint:all -d docs-classic classic/Fees.java
$ sed -n '/<section class="detail" id="discounted/,/<[/]section>/p' docs/Fees.html
<section class="detail" id="discounted(long,int)">
<h3>discounted</h3>
<div class="horizontal-scroll">
<div class="member-signature"><span class="modifiers">public static</span>&nbsp;<span class="return-type">long</span>&nbsp;<span class="element-name">discounted</span><wbr><span class="parameters">(long&nbsp;fee,
 int&nbsp;percent)</span></div>
<div class="block"><p>Returns the fee after a percentage discount.</p>
<p>The discount is rounded down to a whole paisa, so a student never pays less than the advertised rate. For
example, <code>discounted(150_000, 10)</code> returns <code>135_000</code>.</p>
</div>
<dl class="notes">
<dt>Parameters:</dt>
<dd><code>fee</code> - the full fee in paise; must not be negative</dd>
<dd><code>percent</code> - the discount, from 0 to 100</dd>
<dt>Returns:</dt>
<dd>the fee after the discount, in paise</dd>
<dt>Throws:</dt>
<dd><code><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/IllegalArgumentException.html" title="class or interface in java.lang" class="external-link">IllegalArgumentException</a></code> - if <code>fee</code> is negative or <code>percent</code> is outside 0 to 100</dd>
</dl>
</div>
</section>
$ sed -n '/<section class="detail" id="discounted/,/<[/]section>/p' docs-classic/Fees.html | grep -A3 'class="block"'
<div class="block">Returns the fee after a percentage discount.
<p>
The discount is rounded down to a whole paisa, so a student never pays less than the advertised rate. For
example, <code>discounted(150_000, 10)</code> returns <code>135_000</code>.</div>

How a documentation comment is built:

• The first sentence is the summary, the one line shown in the list of methods. The sentences after it are the full description.
• In Markdown a blank /// line starts a new paragraph, and code goes between backticks. The HTML form writes <p> and {@code …} for the same things.
• Block tagsblock tag: A tag at the end of a documentation comment that starts a section of the page: @param for a parameter, @return for the result and @throws for an exception, each followed by its description. come last: @param for each parameter, @return for the result and @throws for each exception a caller should expect. They became the Parameters, Returns and Throws parts of the page.
• A link to another class or method is [String] or [String#strip()] in Markdown, and {@link String#strip()} in the HTML form.
• The /// lines must follow each other without a gap. A blank line, or an ordinary comment, between them splits the comment, and only the last part documents the declaration.

javadoc printed nothing for either version, which means no warnings. The last command printed the description of discounted from the classic version’s page: the same sentences, and the only difference is that the Markdown version puts each paragraph in a <p> of its own. -quiet hides its progress messages, -notimestamp leaves the time stamp out of the pages, so that two runs write the same files, and -d docs names the folder for the pages. The two styles of Fees.java, side by side:

Use /// for new code built with Java 23 or later, and keep /** … */ where the documentation must still build with an older JDK.

doclint reports the comments and tags that are missing

javadoc runs a checker called doclintdoclint: The checker inside javadoc and javac that reports problems in documentation comments, such as a public method with no comment, no @param for a parameter or no @return. -Xdoclint:all turns on every group of checks., switched on by default, which reports problems in documentation comments as warnings. Its checks come in five groups, accessibility, html, missing, reference and syntax. -Xdoclint:all switches every group on, missing included, the one for missing comments and tags, while -Xdoclint:all,-missing would switch on every group but that one. Naming the option keeps a build’s checks from depending on what a JDK’s default happens to be. This class has a comment on its method, but not every part a caller needs:

/// Marks of one student.
public final class HalfDone {
    private HalfDone() {}

    /// Returns the average of the marks.
    public static double average(int[] marks) {
        int total = 0;
        for (int mark : marks) total += mark;
        return (double) total / marks.length;
    }
}

from session import run

run("""
javadoc -quiet -notimestamp -Xdoclint:all -d docs HalfDone.java
javadoc -quiet -notimestamp -Xdoclint:all -Werror -d docs-strict HalfDone.java
""", expect_failure=("javadoc -quiet -notimestamp -Xdoclint:all -Werror -d docs-strict HalfDone.java",))

$ javadoc -quiet -notimestamp -Xdoclint:all -d docs HalfDone.java
HalfDone.java:6: warning: no @param for marks
    public static double average(int[] marks) {
                         ^
HalfDone.java:6: warning: no @return
    public static double average(int[] marks) {
                         ^
2 warnings
$ javadoc -quiet -notimestamp -Xdoclint:all -Werror -d docs-strict HalfDone.java
HalfDone.java:6: warning: no @param for marks
    public static double average(int[] marks) {
                         ^
HalfDone.java:6: warning: no @return
    public static double average(int[] marks) {
                         ^
error: warnings found and -Werror specified
1 error
2 warnings
[exit status 1]

The first run printed both warnings and still ended with exit status 0, so a build that runs it would pass. -Werror turns every warning into an error: the second run printed the same warnings, then error: warnings found and -Werror specified, and failed. That is how a build fails until the documentation is complete. The compiler accepts the same -Xdoclint option, so javac -Xdoclint:all checks documentation while it compiles.

Names follow conventions the compiler does not enforce

The Java Language Specification recommends these conventions, and the JDK’s own classes follow them:

Methods that read a value are named getX, ones that set it setX, ones that answer yes or no isX, and ones that convert toX, as in isEmpty and toString. Good names make the same program readable without comments:

// It works, but no name says what its value means.
void main() {
    int x = 3;
    double y = 4999;
    double z = x * y;
    double t = z - z * 10 / 100;
    IO.println(String.format(Locale.ROOT, "%.2f", t));
}

// The same program, with names that say what each value is.
static final int EARLY_DISCOUNT_PERCENT = 10;

void main() {
    int seats = 3;
    double feePerSeat = 4999;
    double fullFee = seats * feePerSeat;
    double feeAfterDiscount = fullFee - fullFee * EARLY_DISCOUNT_PERCENT / 100;
    IO.println(String.format(Locale.ROOT, "%.2f", feeAfterDiscount));
}

// Legal names that break the conventions: the compiler accepts them all.
void main() {
    int मूल्य = 499;          // letters of any script are allowed
    int seats_left = 4;       // Java style writes seatsLeft
    int $count = 2;           // the dollar sign is meant for generated code
    IO.println(मूल्य + " " + seats_left + " " + $count);
}

from session import run

# The same calculation with poor names and with good ones, then names that are legal but unusual.
run("""
java BadNames.java
java GoodNames.java
java Identifiers.java
""")

$ java BadNames.java
13497.30
$ java GoodNames.java
13497.30
$ java Identifiers.java
499 4 2

Both programs printed 13497.30, but only GoodNames.java tells you that it is a fee for 3 seats after a 10 % discount. The number 10 became the constant EARLY_DISCOUNT_PERCENT, so the next person to change the discount finds it by name instead of guessing which 10 it is.

The conventions are recommendations. The compiler’s rules are looser: a name may use letters and digits of any script, _ and $, must not start with a digit, and must not be a keyword such as class; _ on its own is a keyword too. Identifiers.java compiled a Devanagari name, a snake_case name and a $ name without complaint. Most teams still keep to the conventions and to ASCII letters, so that everyone can read, type and search every name.

final assigns once, and comments that say why age best

final on a variable means it can be assigned only once, and the compiler enforces it:

// final means "assigned once": a second assignment is a compile-time error.
void main() {
    final int maxSeats = 40;
    maxSeats = 45;
    IO.println(maxSeats);
}

from session import run

# FinalCheck.java assigns a final variable twice, and the compiler refuses it.
run("java FinalCheck.java", expect_failure=("java FinalCheck.java",))

$ java FinalCheck.java
FinalCheck.java:4: error: cannot assign a value to final variable maxSeats
    maxSeats = 45;
    ^
1 error
error: compilation failed
[exit status 1]

A constant is a static final field whose value is fixed in the code, such as static final int MAX_SEATS = 40;, and its UPPER_SNAKE_CASE name tells every reader that it never changes. Marking locals final documents that a value is meant to stay the same, and the compiler checks it for you.

Comments age worse than code, because nothing checks them. Compare two comments on the same kind of line:

In documentation comments, describe what a caller may rely on, such as the units, the allowed values and the exceptions, rather than how the method works inside.

Practise: document a utility class

Marks.java is a small class with three public methods and no documentation. Add /// comments to the class and to each public method, with @param for every parameter, @return for every result and @throws for the exception, and run javadoc -quiet -notimestamp -Xdoclint:all -Werror -d docs Marks.java until it prints nothing and finishes with exit status 0.

// Exercise: document this class and its three public methods with /// comments, then run:
//   javadoc -quiet -notimestamp -Xdoclint:all -Werror -d docs Marks.java
// It is done when javadoc prints nothing at all and the exit status is 0.
public final class Marks {
    private Marks() {}

    public static double average(int[] marks) {
        if (marks.length == 0) throw new IllegalArgumentException("no marks");
        int total = 0;
        for (int mark : marks) total += mark;
        return (double) total / marks.length;
    }

    public static int highest(int[] marks) {
        if (marks.length == 0) throw new IllegalArgumentException("no marks");
        int best = marks[0];
        for (int mark : marks) best = Math.max(best, mark);
        return best;
    }

    public static boolean passed(int mark, int passMark) {
        return mark >= passMark;
    }
}

As it starts, javadoc finds four missing comments and stops with an error:

from session import run

# javadoc checks the starter file, which has no documentation comments yet: that is the starting point.
run("javadoc -quiet -notimestamp -Xdoclint:all -Werror -d docs exercise/Marks.java", expect_failure=("javadoc -quiet -notimestamp -Xdoclint:all -Werror -d docs exercise/Marks.java",))

$ javadoc -quiet -notimestamp -Xdoclint:all -Werror -d docs exercise/Marks.java
exercise/Marks.java:4: warning: no comment
public final class Marks {
             ^
exercise/Marks.java:7: warning: no comment
    public static double average(int[] marks) {
                         ^
exercise/Marks.java:14: warning: no comment
    public static int highest(int[] marks) {
                      ^
exercise/Marks.java:21: warning: no comment
    public static boolean passed(int mark, int passMark) {
                          ^
error: warnings found and -Werror specified
1 error
4 warnings
[exit status 1]

A first hint: start each comment with one sentence that says what the method returns, such as /// Returns the average of the marks., then a blank /// line, then the tags. The private constructor needs no comment, because javadoc does not document private members unless you ask it to.

Once javadoc runs clean, the questions below go over the lesson from // to final. A wrong answer is followed by an easier question on the same idea, and every choice tells you what it gets right or misses:

Interview questions

Fresher · What kinds of comments does Java have, and which of them does javadoc read?

Java has end-of-line comments, from // to the end of the line, and block comments, from /* to the next */; block comments do not nest. Documentation comments are a third kind: /** … */ written in HTML with javadoc tags or, since Java 23, consecutive lines starting with ///, written in Markdown. The compiler ignores all of them. The javadoc tool reads only documentation comments, and only when they sit directly before a declaration such as a class, field, constructor or method; it turns them into HTML pages, with block tags such as @param, @return and @throws for the parameter, result and exception sections. A good answer adds one trap: Unicode escapes such as \u000a are processed before comments, so one can end a comment early.

Two longer questions of this module start from this lesson: a commented-out line in a pricing class that still runs, and what the Javadoc of a published library must promise.

Key takeaways

• // comments run to the end of the line and /* … */ comments to the first */, so block comments do not nest; switch code off with // on each line.
• Unicode escapes are replaced before comments are found, so \u000a in a comment ends it, and the code after it runs.
• Documentation comments sit directly above a declaration: /** … */ in HTML, or /// lines in Markdown from Java 23. Their first sentence is the summary, and @param, @return and @throws describe the rest.
• javadoc -d docs writes the HTML, -Xdoclint:all reports missing comments and tags, and -Werror fails the run on any warning.
• Packages are lowercase, types UpperCamelCase, methods and variables lowerCamelCase, constants UPPER_SNAKE_CASE.
• final variables are assigned once and constants are static final; comment why, and let names say what.