Lesson 1.8: Documentation with Comments | AP CSA

Unit 1 · Lesson 1.8 · Conceptual

Lesson 1.8: Documentation with Comments

Reading time: 6–8 min · Practice: 6 exercises · Mastery: applied scenario

What you'll learn in this lesson

  • 1.8.A. Identify and use all three Java comment types: //, /* */, and /** */ (Javadoc), and explain that comments are ignored by the compiler.
  • 1.8.A. Define a precondition as a condition that must be true before a method runs, and explain that the method is not required to check it.
  • 1.8.A. Define a postcondition as a condition that is always true after a method runs, describing the return value or object state.

This lesson is part of the AP CSA Course and Exam Description (effective May 2027).

AP exam weight: The FRQ section regularly includes preconditions in method descriptions. Understanding that a precondition is a guarantee you can rely on (not something the method checks) is critical for writing correct FRQ solutions. Postconditions describe what your code must produce.

Key Vocabulary

Term Definition
single-line comment Text following // on one line; completely ignored by the compiler.
block comment Text between /* and */; can span multiple lines; ignored by the compiler.
Javadoc comment A /** */ comment block read by the javadoc tool to generate HTML API documentation.
precondition A condition that must be true before a method executes; the method is not required to check it.
postcondition A condition guaranteed to be true after a method completes; describes the return value or resulting object state.

Comments: for humans, ignored by the compiler

A comment is text in source code that the compiler completely ignores. Comments exist to help programmers (including yourself six months later) understand what code does. There are three comment types in Java:

The Three Comment Types

// single-line comment
Everything from // to the end of the line is a comment. Used for brief inline notes.

/* multi-line comment */
Everything between /* and */ is a comment, spanning as many lines as needed.

/** Javadoc comment */
A special form of multi-line comment used by the javadoc tool to generate API documentation. It begins with /** (two asterisks) and ends with */.

Example: all three in context

// This method computes the area of a rectangle
/* Both parameters must be positive.
   Returns a double result. */
/**
 * Computes the area of a rectangle.
 * @param width the width of the rectangle
 * @param height the height of the rectangle
 * @return the area as a double
 */
public double area(double width, double height) {
    return width * height;
}

AP Trap: comments do not execute

Comments are stripped out before compilation. A comment that says // x = x + 1 does nothing to the value of x. Students who include logic in comments and wonder why it doesn’t run are confusing documentation with code.

Preconditions

A precondition is a condition that must be true immediately before a method executes in order for the method to behave as described. Preconditions are a contract with the caller: if you call this method with valid inputs, it will do what it says.

Key Rule

There is no expectation that the method will check to ensure preconditions are satisfied. If the caller violates a precondition, the method’s behavior is undefined. It might crash, produce a wrong answer, or do something unpredictable. The contract was broken by the caller, not the method.

Example

/**
 * Returns the square root of n.
 * Precondition: n >= 0
 */
public double sqrt(double n) {
    return Math.sqrt(n);
}

This method does not check whether n >= 0 inside the body. It trusts the caller to satisfy the precondition. If called with a negative value, the behavior is not the method’s responsibility.

Postconditions

A postcondition is a condition that must always be true after a method has executed. Postconditions describe the outcome: what value is returned, or what state an object is in after the call.

Key Rule

Postconditions describe what must be true when the method finishes, assuming preconditions were satisfied. They are what you promise the caller they will get.

Example

/**
 * Adds amount to the account balance.
 * Precondition: amount > 0
 * Postcondition: balance has increased by amount
 */
public void deposit(double amount) {
    balance += amount;
}

The postcondition guarantees that after deposit returns, balance is exactly amount more than it was before the call (assuming the precondition was met).

Tier 2 · AP Practice

Practice Questions

Which comment type is used by the javadoc tool to generate API documentation?
A. // comment
B. /* comment */
C. /** comment */
D. // comment */
C. Javadoc comments begin with /** (two asterisks after the slash) and end with */. The javadoc tool reads these blocks to generate HTML API documentation. Single-line // and block /* */ comments are ignored by javadoc. D is not a valid Java comment syntax.
Consider the following code segment.

int score = 10;
// score = score + 5;
score = score * 2;
System.out.println(score);

What is printed?
Remember: the compiler ignores all comments completely before reading the code.
A. 20
B. 30
C. 25
D. A compile error because the comment contains invalid code.
A. The // score = score + 5; line is a comment and is completely ignored. The code that executes is: score = 10, then score = 10 * 2 = 20. Prints 20. B would result if the comment were executed. D is wrong: comments can contain anything, including code-like text, and the compiler ignores it entirely.
A method has the following documentation:

/**
 * Returns the element at the given index.
 * Precondition: 0 <= index < list.size()
 */

Which of the following best describes what the precondition means?
A. The method will throw an exception if index is out of range.
B. The method checks whether index is valid before executing its main logic.
C. The method returns null if the index is out of range.
D. The caller is responsible for ensuring index is in range; the method does not guarantee correct behavior if this condition is violated.
D. A precondition is a contract with the caller. The method assumes the condition is true and is not required to check it or handle violations. If the caller passes an out-of-range index, the method’s behavior is undefined. A, B, and C all describe what the method does internally—but a precondition makes no such promise.
A method has this postcondition: “The value returned is the largest element in the array.” Which of the following best describes what this postcondition guarantees?
A. The method will throw an exception if there is no largest element.
B. Assuming the preconditions were satisfied, after the method returns, the caller can rely on the returned value being the largest element.
C. The method changes the array so that the largest element is moved to the first position.
D. The method must check every element at least twice to ensure correctness.
B. A postcondition describes what is guaranteed to be true after the method completes, assuming preconditions were met. It is a promise to the caller about the outcome. It says nothing about how the method works internally (ruling out D) and nothing about side effects on the array unless stated (ruling out C).
Which of the following are valid Java comment types according to the AP CSA CED?

I. // single-line comment
II. /* block comment */
III. /** Javadoc comment */
A. I only
B. I and II only
C. I, II, and III
D. II and III only
C. The CED explicitly lists all three comment types: // for single-line, /* */ for block comments, and /** */ for Javadoc. All three are within AP scope.
Consider this method documentation:

/**
 * Sets the temperature of the thermostat.
 * Precondition: temp >= 60 && temp <= 85
 * Postcondition: getTemperature() == temp
 */
public void setTemperature(int temp)

A programmer calls setTemperature(90). Which of the following best describes the situation?
A. The programmer has violated the precondition; the method’s behavior is undefined and it is not required to enforce or report the violation.
B. The method will automatically clamp the temperature to 85 because the postcondition defines the outcome.
C. The postcondition guarantees the method will throw an exception to protect the caller.
D. The precondition is just a suggestion; the method will work correctly with any integer value.
A. The precondition requires temp to be between 60 and 85. Calling with 90 violates it. The method is not required to check the precondition or handle the violation. Its behavior when the precondition is broken is undefined. The postcondition only applies when the precondition is satisfied. B and C describe behaviors the method is not obligated to provide. D incorrectly calls the precondition a suggestion.
Tier 3 · AP Mastery Challenge

The Grade Calculator

A student is writing documentation for a grade-calculation method. Read the method signature and partial Javadoc below.

/**
 * Computes a letter grade from a numeric score.
 * Precondition: ___________________________
 * Postcondition: __________________________
 */
public String letterGrade(int score)

The method returns "A" for scores 90–100, "B" for 80–89, and so on. It does not handle negative scores or scores above 100.

Part A: Identify the correct precondition

Which of the following is the most appropriate precondition for this method?
A. The method will return "F" for any score below 60.
B. The returned String is one of "A", "B", "C", "D", or "F".
C. The method checks whether the score is valid before computing the grade.
D. score >= 0 && score <= 100
D. A precondition states a condition about the inputs that must be true before the method is called. score >= 0 && score <= 100 correctly describes the valid input range the method is designed to handle. A and B describe outcomes (postcondition territory). C describes implementation behavior, which a precondition does not specify.

Part B: Identify the correct postcondition

Which of the following is the most appropriate postcondition for this method?
A. score >= 0 && score <= 100
B. The returned value is one of the Strings "A", "B", "C", "D", or "F", corresponding to the standard grade scale.
C. The method does not modify the value of score.
D. The method uses a series of if-else statements to determine the grade.
B. A postcondition describes what is true after the method completes. For a method that returns a value, the postcondition describes that return value. B correctly describes the guaranteed output. A is the precondition (input constraint). C describes what the method does NOT do (technically a valid postcondition form, but not the most meaningful one here). D describes implementation, which belongs in neither pre- nor postcondition.

Part C: Structured response

A classmate writes a method safeDivide(int a, int b) with the precondition b != 0 and then calls it with safeDivide(10, 0). In three to five sentences, explain what the precondition means, whether the method is obligated to handle this call safely, and what the programmer who wrote the call should have done instead.

Extension · Beyond the Exam

Design by Contract

Preconditions and postconditions come from a software engineering methodology called “Design by Contract,” introduced by Bertrand Meyer. The idea is that a method is a formal contract between the implementer and the caller: the caller promises to satisfy preconditions; the method promises to deliver postconditions. Some languages (like Eiffel) enforce contracts at runtime. Java can approximate this with assert statements, though their use is outside AP exam scope.

Get in Touch

Whether you're a student, parent, or teacher — I'd love to hear from you.

Just want free AP CS resources?

Enter your email below and check the subscribe box — no message needed. Students get daily practice questions and study tips. Teachers get curriculum resources and teaching strategies.

Typically responds within 24 hours
✓

Message Sent!

Thanks for reaching out. I'll get back to you within 24 hours.

🏫 Welcome, fellow educator!

I offer curriculum resources, practice materials, and study guides designed for AP CS teachers. Let me know what you're looking for — whether it's classroom materials, a guest speaker, or Teachers Pay Teachers resources.

✉

Email

[email protected]

📚

Courses

AP CSA, CSP, & Cybersecurity

⏱

Response Time

Within 24 hours

Prefer email? Reach me directly at [email protected]