1.8 Documentation with Comments

1.8 Documentation with Comments

A Java comment can explain what a method expects and guarantees without changing a single step of program execution. Good documentation acts like a contract between a method and its caller: before calling, the caller must satisfy certain conditions; after the method finishes, the method promises certain results.

Documentation comments describe a method’s purpose, parameters, required conditions, and results for the humans who use or maintain the code.

From comments to method contracts

A method contract is the complete agreement between a method and its caller. It usually contains four parts:

• Purpose: What the method does.
• Parameters: What information the caller supplies.
• Preconditions: What must already be true before the call.
• Postconditions: What the method guarantees after execution.

A precondition is an assumption that must be true before a method is called. A postcondition is a guarantee about the program state or return value after the method executes.

A documentation comment’s information flow

Caller checks preconditions
          |
          v
     method call
          |
          v
Method performs its behavior
          |
          v
Caller relies on postconditions

For example, imagine a Bottle object that removes liquid. The caller may request a removal only when the amount is greater than zero and no greater than the amount currently remaining. Those are preconditions because they must be true before the method begins.

The method also has a postcondition involving the bottle’s capacity: if removing the requested amount would leave less than $25%$ of the bottle’s capacity, the bottle is refilled. The postcondition describes what the method guarantees after execution, not merely what it usually attempts to do.

/**
 * Removes liquid from the bottle.
 *
 * Precondition: amount > 0 and amount <= current liquid amount
 * Postcondition: if the removal would leave less than 25 percent
 * of the bottle's capacity, the bottle is refilled
 *
 * @param amount the quantity of liquid to remove
 */
public void removeLiquid(double amount) {
    // method implementation
}

Javadoc-style specifications

A documentation comment placed immediately before a method or constructor commonly uses Javadoc-style notation. It begins with /** and ends with */. Tags such as @param identify parameters, while @return describes a value produced by a non-void method.

The comment should make the method understandable without forcing a reader to inspect every implementation statement. For a username method, documentation might state constraints such as username.length() >= 2 and no consecutive hyphens.

/**
 * Determines whether a username follows the required format.
 *
 * Precondition: username is not null
 * Postcondition: returns true exactly when the username has at least
 * 2 characters and contains no consecutive hyphens
 *
 * @param username the username to check
 * @return whether the username satisfies the required constraints
 */
public boolean isValidUsername(String username) {
    return username.length() >= 2
        && !username.contains("--");
}

The expressions username.length() >= 2 and “no consecutive hyphens” are not implementation details; they tell callers what input is acceptable and what result to expect. A caller can therefore decide whether a proposed username is valid before relying on the method’s return value.

Constructors need documentation too

A constructor’s documentation describes the object being created and the information required to initialize it. For a name-based object, the specification can state that the constructor receives a first name and a last name, with the last name having a length of at least $1$.

/**
 * Constructs a name using the given first and last names.
 *
 * Precondition: lastName.length() >= 1
 *
 * @param firstName the person's first name
 * @param lastName the person's last name
 */
public Name(String firstName, String lastName) {
    this.firstName = firstName;
    this.lastName = lastName;
}

A constructor comment should not pretend to return a value: constructors initialize a new object, so they have no @return tag. Its documentation instead explains the required arguments and the state established in the new object.

Describing a return value

The getSignature method has no parameters and returns a formatted signature string based on the first and last names. Its documentation should explicitly communicate both facts.

/**
 * Returns a formatted signature based on the first and last names.
 *
 * @return the formatted signature string
 */
public String getSignature() {
    return firstName + " " + lastName;
}

The absence of @param is meaningful here: the method takes no parameters. The @return description tells the caller what kind of result to expect and what information that result represents.

Misconception check: comments are not enforcement

Misconception: Writing “Precondition: amount > 0” causes Java to reject invalid values automatically.

Correction: A documentation comment does not affect execution. It communicates an agreement; the method or its caller must supply any actual validation or error handling. If the comment says a username must have at least $2$ characters but the code never checks that condition, the documentation and implementation disagree.

This is why documentation must match the code’s real behavior. An inaccurate postcondition is especially dangerous: callers may make decisions based on a guarantee the method never actually provides.

AP skills and reasoning processes

Topic 1.8 Documentation with Comments most directly develops Skill 1.A: Represent and describe how a program works by requiring precise explanations of a method’s purpose, inputs, assumptions, and results. It also supports Computational Thinking Practice 4—Document Code and Computing Systems, because documentation communicates behavior to people who read, test, reuse, or maintain the program.

In-flow retrieval check: A method removes liquid only when $0 < amount \leq$ the current amount, and it refills the bottle whenever the removal would leave less than $25%$ of capacity. Which statement is the precondition, and which is the postcondition?

Answer: The valid range for amount is the precondition because it must be true before the call. The refill rule is the postcondition because it describes what the method guarantees after the call.