Method Parameters and Return Values

A Javadoc comment begins with /** and ends with */, and has the same form as a /* */ block comment.

Programming

A Documented Method That Disagrees

Programs are often read by people other than the person who wrote them, and the Java API is documentation-heavy by design. A comment that describes a method is only useful while it stays true. When the comment says one thing and the code does another, the comment becomes a source of bugs rather than a help. This article shows how to read a documented method closely enough to notice when the two no longer agree.

java

/**
 * Returns the price after a percentage discount.
 *
 * @param price the original price, must not be negative
 * @param rate the discount as a percentage from 0 to 100
 * @return the price after the discount is subtracted
 * @throws IllegalArgumentException if price is negative
 */
public static double discountedPrice(double price, double percent) {
    if (price < 0) {
        throw new IllegalArgumentException("price must not be negative");
    }
    return price - price * percent / 100;
}

/**
 * Returns the price after a percentage discount.
 *
 * @param price the original price, must not be negative
 * @param rate the discount as a percentage from 0 to 100
 * @return the price after the discount is subtracted
 * @throws IllegalArgumentException if price is negative
 */
public static double discountedPrice(double price, double percent) {
    if (price < 0) {
        throw new IllegalArgumentException("price must not be negative");
    }
    return price - price * percent / 100;
}

Notes on the code

The comment block opens with /** and closes with */
The method signature declares two parameters: price and percent
The first @param tag names price, which matches a real parameter

What do you think happens?

Before reading on, look at the two @param tags. Which one does not describe a real parameter of this method?

Reveal answer

Answer:

The second @param tag, which names rate. The method signature declares percent, not rate, so the tag does not refer to any real parameter.

Each @param name must match a real parameter. The description after the name is correct in spirit, but the name is what ties the tag to the code, so the mismatch is the first thing to check.

What Makes a Javadoc Comment

Definition

A Javadoc comment is a special comment in Java source code that begins with /** and ends with */. It takes the same form as an ordinary block comment, which begins with /* and ends with */. The only difference is the extra asterisk at the start.

What exactly differs between a /* */ block comment and a /** */ Javadoc comment, and which one can documentation tools read?

Key point

The two forms differ by a single character. Opening with /* where /** was intended turns the documentation into a plain comment, so the tags inside it are no longer prepared as documentation.

Reading a Javadoc comment left to right shows its parts in order: it opens with /**, contains tags on their own lines, and closes with */. Knowing this order makes it easier to notice a missing piece, such as a comment that opens correctly but is never closed.

The Three Tags

Javadoc tags carry specific information inside a Javadoc comment. The three tags covered here are @param, @return, and @throws. Each follows a fixed pattern: a tag name, then a specific piece of information, then a description.

Tag	Required piece after the tag	What the description explains
@param	The name of a real parameter of the method	What the parameter is for and what values it may take
@return	No name; the description starts right after the tag	What the method gives back to its caller
@throws	The exception class name	The situation in which that exception is thrown

The shape of each tag. @param and @throws require a name before the description; @return does not.

Tracing the Documented Method

Tracing means reading the comment and the code together, one tag at a time. For each @param tag, find the matching parameter in the signature. For the @return tag, find the line that returns a value. For each @throws tag, find the line where that exception can be thrown. A tag that cannot be matched to anything in the code is a divergence.

Which parameter in the signature does each @param tag document, and where does a tag name something that does not match a real parameter?

Worked example

Locating the divergence in discountedPrice

The method signature is discountedPrice(double price, double percent). Its Javadoc has two @param tags, one named price and one named rate. Find where the documentation and the code disagree.

1
Read the signature
The real parameters are price and percent. Those are the only names a @param tag can legitimately use.
2
Match the first tag
@param price names price, which exists in the signature. This tag matches.
3
Match the second tag
@param rate names rate, which does not exist in the signature. The description talks about a discount percentage, which is the job of percent, so the name is the divergence.
4
Check the other tags
@return describes the price after the discount, and the final return line subtracts the discount, so it agrees. @throws IllegalArgumentException matches the if-check that throws it when price is negative.

Result

The only divergence is the @param name. The tag should read @param percent, so the comment describes the real parameter.

java

/**
 * Returns the price after a percentage discount.
 *
 * @param price the original price, must not be negative
 * @param percent the discount as a percentage from 0 to 100
 * @return the price after the discount is subtracted
 * @throws IllegalArgumentException if price is negative
 */
public static double discountedPrice(double price, double percent) {
    if (price < 0) {
        throw new IllegalArgumentException("price must not be negative");
    }
    return price - price * percent / 100;
}

/**
 * Returns the price after a percentage discount.
 *
 * @param price the original price, must not be negative
 * @param percent the discount as a percentage from 0 to 100
 * @return the price after the discount is subtracted
 * @throws IllegalArgumentException if price is negative
 */
public static double discountedPrice(double price, double percent) {
    if (price < 0) {
        throw new IllegalArgumentException("price must not be negative");
    }
    return price - price * percent / 100;
}

Notes on the code

The corrected @param tag now names percent, matching the signature
Every other tag was already consistent with the code and is unchanged

Where @throws Comes From

A @throws tag documents an exception the method can actually throw. To check it, follow the path through the method body: find the statement that throws, decide whether a condition leads to it, and see whether the exception reaches the caller. The flowchart below traces the discountedPrice method for the case that matters.

Where does an exception originate in the method body, and how does it propagate to the caller, so that the @throws tag should document it?

Read the diagram as the justification for the tag. The exception originates in the if-branch, and it reaches the caller because the method does not catch it. That is why @throws IllegalArgumentException belongs in the comment. If someone removed the check but left the tag, the comment would promise an exception the code can no longer throw.

Mistakes Beginners Make with Javadoc

Common mistake
Typing /* where /** was intended
What it looks like
/* Returns the price after a discount. ... */ placed above the method
Why it fails
The extra asterisk is what makes the comment Javadoc. With /* the comment is an ordinary block comment, and its tags are not prepared as documentation.
Do this instead
Open the comment with /** and close it with */.
Common mistake
Naming a @param that does not match any parameter
What it looks like
@param rate on a method whose signature declares percent
Why it fails
Each @param name must match a real parameter. A mismatched name means the comment describes something the method does not have.
Do this instead
Compare each @param name with the signature and rename the tag to the real parameter.
Common mistake
Writing a @throws tag for an exception the method cannot throw
What it looks like
@throws IllegalArgumentException on a method whose body contains no throw statement
Why it fails
A @throws tag documents an exception the method can actually throw. Without a path to the throw, the tag promises behavior the code does not have.
Do this instead
Find the throw statement in the body, confirm the condition that reaches it, and keep the tag only if that path exists.
Common mistake
Leaving a Javadoc comment unclosed, so the */ that ends it is missing

Practice: Find the Divergence

MEDIUM

The method below is documented with a Javadoc comment. Read its tags against its signature and body. Identify every place where the comment and the code disagree, and state what each tag should say.

/**
 * Sums two integers.
 *
 * @param first the first addend
 * @param second the second addend
 * @return the sum of the two values
 * @throws ArithmeticException if the sum overflows
 */
public static int addTwo(int a, int b) {
    return a + b;
}

Hints

Start with the @param tags. Compare each name against the parameters in the signature, which are a and b.
Next check the @throws tag. Search the method body for any statement that can throw ArithmeticException.
The @return tag should agree with the return statement. Check whether the description says anything the code does not do.

Your attempt (not saved)

Key Takeaways

A Javadoc comment begins with /** and ends with */, the same form as a /* */ block comment with one extra asterisk.
@param, @return, and @throws carry a parameter name, a return value description, and an exception class name respectively, with @param and @throws requiring a name before the description.
Each @param name must match a real parameter, and each @throws must name an exception class, so these are the parts to check first.
To find a divergence, compare each tag with its matching line of code: the parameter in the signature, the return statement, or the throw statement.
The skill that matters most in debugging is noticing when a documented method no longer behaves as its comment claims.