AP Computer Science A • Unit 1.8

Documentation with Comments

Detailed answer explanations for the Unit 1.8 multiple-choice practice questions.

Q1D
Q2A
Q3D
Q4A
Q5D
Q6B
Q7C
Q8B
Q9C
Q10A
Q11B
Q12D
How to use this page: First try each question without looking at the explanation. Then compare your answer with the key and read why the other choices are not correct.

Answer Explanations

Q1

Consider the following method documentation. Which of the following calls satisfies the documented preconditions?

/**
 * Returns the percentage of pages read.
 * Precondition: total > 0.
 * Precondition: 0 <= read <= total.
 */
public double readPct(int total, int read)
AreadPct(0, 0)
BreadPct(20, 24)
CreadPct(20, -1)
DreadPct(20, 8)
Correct answer: D. The call readPct(20, 8) is the only one whose total is positive and whose page count stays within range.
Explanation

A precondition states what must be true when a method is called, and the code making the call is responsible for satisfying it. Both documented conditions apply at once: the total must be greater than zero, and the pages read must fall from zero through the total.

  • A is not correct: the first precondition requires a total greater than zero, and readPct(0, 0) passes a total of 0 instead.
  • B is not correct: the second precondition allows the pages read to reach only the total, and readPct(20, 24) passes a larger count.
  • C is not correct: the second precondition requires the pages read to be at least zero, and readPct(20, -1) falls below that limit.
Q2

Consider the following method documentation. Which of the following best describes the documented postcondition?

/**
 * Returns the larger of a and b.
 * Postcondition: the returned value is greater 
 * than or equal to both a and b.
 */
public int max(int a, int b)
AThe method returns a value that is at least as large as both arguments.
BThe method must be called only when a is positive.
CThe method must be called only when b is positive.
DThe method changes both parameter values before returning.
Correct answer: A. The documented postcondition promises a returned value greater than or equal to both a and b.
Explanation

A postcondition describes what a method guarantees after it finishes, provided that its preconditions were satisfied. This comment makes no demand on the caller; it states the property the result will have once the method returns.

  • B is not correct: this states a requirement that would have to hold before the call, which would make it a precondition rather than a postcondition.
  • C is not correct: this also describes a restriction on a value supplied before the call, and the documented postcondition restricts nothing about b.
  • D is not correct: a postcondition may describe the returned value or a change the method makes, but this one promises only a size relationship for the result.
Q3

Consider the following method and documentation. Which of the following best describes the documentation?

/**
 * Returns the sum of a and b.
 */
public int combine(int a, int b) {
  return a * b;
}
AIt is accurate because the method returns the sum of a and b.
BIt is unnecessary but accurate because multiplication and addition are equivalent.
CIt is invalid because Javadoc comments cannot be used before methods.
DIt is misleading because the comment says sum, but the code returns a product.
Correct answer: D. The comment claims the method returns a sum while the code returns a * b, so the documentation misleads.
Explanation

Documentation must change when the code changes. An outdated or inaccurate comment can be worse than no comment, because it confidently describes behavior the program does not have and a reader expects the wrong result.

  • A is not correct: the body returns a * b, which is a product, so the claim that a sum comes back does not match the code.
  • B is not correct: multiplication and addition are different operations that give different results, so a comment describing one cannot accurately describe the other.
  • C is not correct: a Javadoc comment appears immediately before the code it describes, so placing one before a method is exactly where it belongs.
Q4

Which of the following begins a Javadoc comment?

A/**
B//
C/*
D#
Correct answer: A. A Javadoc comment begins with /** and ends with */, the form the Javadoc tool reads.
Explanation

Java has three common comment styles. A single-line comment begins with //, a block comment begins with /*, and a Javadoc comment follows a structure that the Javadoc tool can turn into browsable API documentation.

  • B is not correct: // begins a single-line comment, which continues only to the end of the line it appears on.
  • C is not correct: /* begins an ordinary block comment, which may span multiple lines but lacks the structure the Javadoc tool turns into documentation.
  • D is not correct: # is not one of the three comment styles in Java, which use //, /*, and /**.
Q5

Who are comments intended to help?

AOnly the compiler
BOnly the original programmer
COnly programmers who did not write the code
DBoth the original programmer and other programmers
Correct answer: D. Documentation helps the original programmer and everyone who reads the code later, which matters especially when code is reused.
Explanation

The compiler ignores comments, so comments are written for people. A programmer may call a method written by someone else and still need to know what it expects, what it returns, and what it promises when it finishes.

  • A is not correct: the compiler ignores comments entirely, so documentation is written for people to read rather than for the compiler.
  • B is not correct: the original programmer benefits, but so does everyone who reads the code later, which is why reuse makes documentation valuable.
  • C is not correct: the programmer who wrote the code still relies on recorded purpose, requirements, and expected results that the instructions alone may not show.
Q6

What can the Javadoc tool create from a Javadoc comment?

AExecutable bytecode
BAPI documentation
CA run-time error report
DA new Java data type
Correct answer: B. The Javadoc tool reads the structure of a Javadoc comment and turns it into browsable API documentation.
Explanation

A Javadoc comment begins with /** and ends with */. Unlike an ordinary block comment, it follows a structure, including tags such as @param and @return, that the tool can present to readers.

  • A is not correct: the compiler ignores comments, so the text of a comment never becomes part of the instructions the program carries out.
  • C is not correct: a comment records intent, assumptions, and guarantees for readers; it does not report what goes wrong while a program is running.
  • D is not correct: documentation describes code that already exists, such as parameters and a returned value, rather than defining anything new in the language.
Q7

Which comment is most useful?

A// Add 1 to count before count++;
B// Set x equal to y before x = y;
C// Convert total points into a percentage before comparing cutoffs.
D// This is a method.
Correct answer: C. The comment about converting total points records intent, explaining why the conversion happens before the cutoffs are compared.
Explanation

Good documentation does not replace clear code. It records intent, assumptions, and guarantees that may not be obvious from the instructions alone, while a comment that merely translates one line of code into English adds little value.

  • A is not correct: // Add 1 to count restates count++; in English and adds nothing the line itself does not already show.
  • B is not correct: // Set x equal to y repeats the assignment x = y; in words, so it records no intent or assumption.
  • D is not correct: // This is a method. labels the code without recording purpose, requirements, or expected results for a later reader.
Q8

Who is responsible for satisfying a documented precondition before a method is called?

AThe compiler
BThe code that calls the method
CThe return statement
DThe Java Virtual Machine after the method finishes
Correct answer: B. A documented precondition is the responsibility of the code making the call unless the method says it checks the values itself.
Explanation

A precondition is an assumption, not necessarily a condition checked inside the method. Because the assumption is documented, the method may rely on it while doing its work, as when it divides by totalPages without checking for zero.

  • A is not correct: the compiler ignores comments, so it cannot enforce a condition that exists only in the documentation of a method.
  • C is not correct: a return statement produces the value the method sends back; it does nothing about assumptions that must hold before the call.
  • D is not correct: a precondition must already be true when the method is called, so anything happening after the method finishes comes too late.
Q9

What happens if only a comment in a Java program is changed?

AThe program must be compiled into a different data type.
BThe comment becomes part of the program's output.
CThe program's execution behavior does not change because comments are ignored by the compiler.
DThe program produces a run-time error.
Correct answer: C. The compiler ignores comments, so changing only a comment leaves the program's execution behavior exactly as it was.
Explanation

Code tells the computer what to do, and documentation makes code easier for people to understand. Because comments are ignored by the compiler, editing one changes what a reader sees rather than the instructions the program carries out.

  • A is not correct: a comment carries no instructions and is not a value with a type, so rewording one changes nothing about how the code is compiled.
  • B is not correct: comments are ignored by the compiler, so their text never becomes part of what the program displays when it runs.
  • D is not correct: a comment contains nothing for the program to carry out, so changing its wording cannot cause a failure while the program runs.
Q10

Which of the following is a correctly written Java block comment?

A/* Calculate the final score. */
B/** Calculate the final score.
C// Calculate the final score. */
D# Calculate the final score.
Correct answer: A. A block comment begins with /* and ends with */, and this choice contains both markers.
Explanation

A block comment begins with /*, ends with */, and can span multiple lines. Both markers are needed, while a single-line comment instead begins with // and continues to the end of the line.

  • B is not correct: /** opens a Javadoc comment rather than an ordinary block comment, and no closing */ appears to end it.
  • C is not correct: // begins a single-line comment that runs to the end of the line, so the trailing */ closes nothing.
  • D is not correct: # is not one of the three comment styles in Java, so this line does not open a block comment.
Q11

Which statement correctly distinguishes a precondition from a postcondition?

AA precondition describes the return type, while a postcondition describes the parameters.
BA precondition must be satisfied before the call, while a postcondition states what is guaranteed after the method finishes.
CA precondition is checked by the compiler, while a postcondition is checked by the JVM.
DA precondition describes a comment, while a postcondition contains executable code.
Correct answer: B. A precondition must hold before the call, and a postcondition states what the method guarantees after it finishes.
Explanation

A precondition must be true when a method is called, and the method may rely on it while doing its work. A postcondition describes what the method promises afterward, provided the preconditions were satisfied, such as the range of the result.

  • A is not correct: neither condition names a part of the header; the @param and @return tags describe the parameters and the returned value instead.
  • C is not correct: the compiler ignores comments, so neither condition is checked automatically; a precondition is an assumption the calling code is expected to satisfy.
  • D is not correct: both are written as documentation, so neither one contains instructions that run; a postcondition records a promise about the result.
Q12

Who is responsible for making a documented postcondition true when the method finishes?

AThe code that calls the method
BThe compiler
CThe Java Virtual Machine
DThe method's implementation
Correct answer: D. The method's own implementation produces the promised result, so it makes the documented postcondition true when the method finishes.
Explanation

A postcondition describes what a method guarantees after it finishes, provided its preconditions were satisfied. The promise concerns the returned value or a change the method makes, and both come from the instructions written inside the method.

  • A is not correct: the calling code is responsible for the documented preconditions, while the promise about the result comes from the method itself.
  • B is not correct: the compiler ignores comments, so it neither reads a documented promise nor arranges for the result to satisfy one.
  • C is not correct: running the program does not by itself make a documented promise true; the guarantee comes from the instructions the method performs.