How do comments, preconditions and postconditions document a method's behavior?
Topic 5.3 Documentation with Comments: write comments that document a method, including its precondition and postcondition, to describe what the method assumes and guarantees.
A focused answer to AP CSA Topic 5.3, covering line and block comments, what makes a useful comment, preconditions and postconditions, why they form a contract for a method, and how they guide both callers and implementers, with a fully worked example.
Reviewed by: AI editorial process; not yet individually human-reviewed
Have a quick question? Jump to the Q&A page
Jump to a section
What this topic is asking
The College Board (Topic 5.3) wants you to document code with comments, and in particular to express a method's precondition (what must be true before it is called) and postcondition (what it guarantees afterward). Together these form a contract: the caller promises the precondition, and in return the method promises the postcondition. Reading and writing this documentation is essential for the free-response section, where methods are specified by exactly this kind of contract.
Kinds of comments
Java ignores comments when running; they are for human readers.
// line commentruns to the end of the line./* block comment */can span multiple lines.
int total = 0; // running sum, starts at zero
/* The loop below visits every element once. */
What makes a comment useful
Preconditions
For example, a getElement(int index) method might state "Precondition: 0 <= index < size". A caller must check the index; the method may assume it is valid and skip its own checking.
Postconditions
A postcondition for a sort method might be "Postcondition: the array is in non-decreasing order, and the same elements are present". The caller can rely on this without inspecting the method's internals.
The contract view
Precondition and postcondition together describe a method as a contract: "if you (the caller) ensure the precondition, then I (the method) promise the postcondition". This lets callers use a method by its documentation alone, and lets implementers reason about correctness locally. AP free-response questions are written as exactly this kind of contract: the prompt gives you the precondition and the required postcondition, and you implement the body.
Try this
Q1. Whose responsibility is it to ensure a method's precondition is satisfied? [1 point]
- Cue. The caller's - the method assumes the precondition is already true on entry.
Q2. Explain the difference between a precondition and a postcondition. [2 points]
- Cue. A precondition is what must be true before the method runs (the caller's responsibility); a postcondition is what the method guarantees to be true after it returns (the implementer's responsibility, assuming the precondition held).
Exam-style practice questions
Practice questions written in the style of College Board exam questions on this dot point, with worked answer explainers. The year tag is the paper they imitate, not the source.
AP 2021 (style)1 marksMultiple choice. A method's documentation states: "Precondition: divisor != 0". What does this precondition mean?
(A) The caller is responsible for ensuring divisor is not zero before calling the method.
(B) The method will throw an exception if divisor is zero.
(C) The method will set divisor to a non-zero value automatically.
(D) The method returns zero when divisor is zero.
(E) The precondition has no effect on how the method may be used.
Show worked answer →
The answer is (A).
A precondition is a condition the method assumes is already true when it is called; it is the caller's responsibility to satisfy it. The method does not have to behave sensibly if the precondition is violated. (B) describes defensive programming, which a precondition explicitly avoids requiring. (C) and (D) invent behavior the precondition does not promise. (E) is wrong because the precondition tells callers exactly how the method may be used.
Markers reward stating that a precondition is the caller's obligation, assumed true on entry.
AP 2020 (style)3 marksFree response (code writing). Write a method header and documentation comment for a method `average` that returns the `double` average of two `int` parameters `a` and `b`. Include a one-line description, and state a postcondition describing the returned value. The method body may be a single return statement.
Show worked answer →
A 3-point question testing a documented method.
// Returns the average of a and b as a double.
// Postcondition: the returned value equals (a + b) / 2.0.
public double average(int a, int b) {
return (a + b) / 2.0;
}
Point 1: a clear description comment of what the method does. Point 2: a postcondition stating what is guaranteed about the return value. Point 3: a correct header and body that divides by 2.0 (a double) so the result is not truncated by integer division. Dividing by 2 instead of 2.0 would silently break the postcondition.
Related dot points
- Topic 5.6 Writing Methods: design and implement methods that take parameters, perform a computation possibly using the object's instance variables, and return a result or perform an action.
A focused answer to AP CSA Topic 5.6, covering the method header (modifiers, return type, name, parameters), how a method uses instance variables and parameters, returning a value versus void, calling one method from another, and tracing a method, with a fully worked example.
- Topic 5.2 Constructors: write constructors that initialise an object's instance variables from parameters, including overloaded and default constructors, and explain the default initial values.
A focused answer to AP CSA Topic 5.2, covering constructor syntax, initialising instance variables from parameters, the no-argument constructor, overloading, default values when a variable is not set, and the difference between a parameter and an instance variable, with a fully worked example.
- Topic 5.4 Accessor Methods: write accessor (getter) methods, including a toString method, that return information about an object's state without changing it.
A focused answer to AP CSA Topic 5.4, covering accessor (getter) methods, the non-void return type, why accessors do not change state, the toString method and how println uses it, and returning computed values, with a fully worked example.
- Topic 5.1 Anatomy of a Class: identify the parts of a class definition (the class header, private instance variables, constructors and methods) and explain encapsulation through access modifiers.
A focused answer to AP CSA Topic 5.1, covering the class header, private instance variables, constructors and methods, the meaning of public and private, encapsulation, and how the pieces combine into a working class, with a fully worked example.
- Topic 2.5 Calling a Non-void Method: call a method that returns a value, and use the returned value by storing it, printing it, or including it in an expression.
A focused answer to AP CSA Topic 2.5, covering methods that return a value, the return type, using a returned value in an assignment, expression or print, the difference from a void method, and chaining method calls, with a worked trace.
Sources & how we know this
- AP Computer Science A Course and Exam Description — College Board (2025)