1.8 Documentation with Comments

What you need to know

• // starts a single-line comment. /* ... */ is a multi-line comment. /** ... */ is a Javadoc comment, used to document classes and methods.
• A precondition is a condition that must be true before a method is called for it to work correctly. The method is not required to check it — the caller is responsible.
• A postcondition is a condition that will be true after the method finishes, assuming preconditions were met. It describes what the method guarantees.
• On FRQs, the problem statement gives preconditions (e.g., "the array contains at least one element"). You may rely on them — you don't need to handle cases they rule out.
• Good comments explain intent and non-obvious decisions. Restating the code (x++; // add one to x) adds nothing.
• Documentation helps future readers, including you, and is part of a professional development process.

Worked example

/**
 * Returns the average of the values in nums.
 * Precondition: nums.length > 0
 * Postcondition: the returned value is the sum of the
 *                elements divided by nums.length
 */
public static double average(int[] nums)
{
    // no need to check for empty array: precondition handles it
    ...
}

Going deeper

The nuance, edge cases, and connections that turn a 3 into a 5.

• A precondition is a promise the caller makes: "I will only call this with valid input." The method can assume it's true. On FRQs, when a precondition says "the array is non-empty," you don't check for empty — doing so wastes time and can even introduce bugs.
• A postcondition is a promise the method makes: "when I return, this will be true." It describes the result, not the process. Different implementations can satisfy the same postcondition.
• Preconditions and postconditions are the formal version of an API contract. They let you use a method without reading its code: know what it needs, know what it guarantees.
• Comments explain why, not what. i++; // increment i is noise. i++; // skip the header row is documentation.
• Javadoc comments (/** */) before a class or method are extracted by tools into API documentation. That's how the official Java docs are generated. The exam may show them; you won't be asked to write them.
• Reading FRQ problem statements is reading documentation: every method you're given comes with a description, sometimes preconditions, and the expected behavior. Students who skim lose points to details that were spelled out.

Mistakes that cost points

• Checking preconditions inside the method on an FRQ. Not wrong, but wasted effort, and if your check is buggy it costs points. Trust the precondition.
• Confusing pre and post. Pre = about inputs, before. Post = about outputs/state, after.
• Restating code in comments. The exam won't penalize it, but it signals not understanding what comments are for.

Practice questions

Written in the style of the real exam. Try each one before revealing the answer.