Documentation with Comments and Preconditions

Three Kinds of Comments

// single-line comment
/* multi-line
   comment */
/** a documentation comment — describes a class or method for other programmers */

The compiler ignores all three completely — they exist for whoever reads the code next, including future-you.

Java 25 note: Java 23 added a fourth style, /// Markdown documentation comments, where every line of the comment starts with ///. This course uses /** */, which works on every Java version — on Java 17, a /// line is just an ordinary // comment.

Preconditions and Postconditions

A precondition is what has to be true before a method is called for it to work correctly. A postcondition is what's guaranteed true after it runs.

The method below takes a parameter, which Lesson 4.1 covers properly — for now, just look at the comment above it:

/**
 * Spins the shooter up toward a target speed.
 * Precondition: targetRPM is between 0 and the motor's max RPM.
 * Postcondition: the motor ramps toward targetRPM.
 *
 * @param targetRPM the speed to spin up to
 */
public void spinUpTo(double targetRPM) { ... }

A documentation comment starts with a plain description — here, what the method does plus its precondition and postcondition — and ends with its tags. @param describes one parameter. Keep the tags last: everything after a tag is treated as part of that tag's description.

Java doesn't enforce preconditions automatically — nothing stops you from calling spinUpTo(-500). A precondition is a documented expectation, not a guarantee the method checks it. A real library shows the same effect: Math.sqrt(-4) (Java's Math class is Lesson 4.3) doesn't crash — its documentation says a negative input gives NaN ("not a number"). If your code needed a real distance, NaN is a silent wrong answer, not an error.

More Documentation Tags

Two more tags show up constantly in library documentation:

/**
 * Converts a battery voltage into an approximate charge percentage.
 *
 * @param volts the measured battery voltage
 * @return the charge, from 0 to 100
 * @throws IllegalArgumentException if volts is negative
 */
public static double batteryPercent(double volts) { ... }

• @return describes the value the method hands back (return values are Lesson 4.2).
• @throws names an error (an exception) the method can throw, and when it happens (exceptions are Ch.12).

Your IDE reads these comments too: hover over a call to batteryPercent and it shows the description and tags. The javadoc tool turns the same comments into web pages — which is exactly how a library's API pages are made.

Reading an API Page

WPILib's API pages are generated from its own /** */ comments. The 2027 pages are at github.wpilib.org/allwpilib/docs/beta/java/ — search there for a class by name. The page for WPILib's Timer class shows, top to bottom:

• Package and class — org.wpilib.system, class Timer. The package tells you what to import (Lesson 3.3).
• Class description — "A timer class."
• Constructor Summary — Timer(): how to build one with new, and what it needs (no arguments).
• Method Summary — one row per method: its return type, its name and parameters, and a one-line description. double get() — "Get the current time from the timer." void start() — "Start the timer running." boolean hasElapsed(double seconds) — "Check if the period specified has passed."
• Method Details — the full comment for each method, including its @param and @return text.

The row double get() tells you everything you need to call it: no arguments, and it hands back a double — the timer's elapsed time in seconds.

Why Bother Documenting This

Once you write a method, other people (including future-you, and your whole team) will call it without reading its implementation. Documenting preconditions and postconditions is how they know what's safe to pass in and what to expect back — without documentation, the only way to find out is to read the method's full source or guess.

Common Pitfalls

• Assuming a precondition is enforced. Documenting a precondition doesn't make Java check it — passing a bad value can still silently produce a wrong result (like NaN) instead of an error.
• Skipping documentation on methods other people will call. The cost of a two-line comment is much smaller than the cost of a teammate guessing wrong about what a method expects.
• Putting description text after the tags. Anything written after @param becomes part of that parameter's description — write the description first, then the tags.

Key Takeaways

• //, /* */, and /** */ are the three comment styles; the compiler ignores all of them. (Java 23+ also allows /// documentation comments.)
• A precondition is what must be true before a method is called; a postcondition is what's guaranteed true after it returns.
• Preconditions are documented expectations, not automatically enforced — violating one can produce a wrong result without an error.
• A /** */ comment starts with its description, then its tags: @param for each parameter, @return for the returned value, @throws for errors.
• An API page lists a class's package, constructors, and methods (return type, name, parameters, description) — all generated from comments like these.

Derived from csawesome-2026: unit-1-using-objects-and-methods/1.08-documentation-with-comments-and-preconditions.md (CSA 1.8)