1.8 Documentation With Comments

TLDR

Comments in AP Computer Science A explain what your code does and how to use it correctly, and they are completely ignored by the compiler when the program runs. Java has three comment styles: single-line //, block /* */, and Javadoc /** */, which is used to build API documentation. You also need to know preconditions (what must be true before a method runs) and postconditions (what is true after it finishes).

more resources to help you study

practice multiple choiceFRQ practice & scoringcheatsheetsscore calculator

What Are Java Comments in AP CSA?

Java comments are notes for programmers that describe what code does, how a method should be used, or what conditions a method depends on. The compiler ignores comments, so they do not execute or change the program's output, but they help you understand preconditions, postconditions, and API-style documentation on the AP Computer Science A exam.

Why This Matters for the AP Computer Science A Exam

This topic builds your ability to describe the conditions a method needs in order to work as intended. That skill shows up when you read a method's documentation and have to figure out how to call it correctly or predict its behavior.

On the exam, comments and documentation help you in two main ways. First, multiple-choice questions often show method headers with comments that state preconditions and postconditions, and you have to use that information to pick the right answer. Second, when you write free-response code, the provided method documentation tells you exactly what inputs you can assume and what your method must produce. Reading preconditions and postconditions carefully keeps you from writing code that checks for things the problem already guarantees.

Key Takeaways

• Comments are written for humans, not the computer; the compiler ignores them and they never run.
• Java has three comment types: // for a single line, /* */ for a block, and /** */ for Javadoc that generates API documentation.
• A precondition is what must be true just before a method runs for it to behave correctly. The method is not expected to check it.
• A postcondition is what must be true after a method finishes, usually describing the return value or the object's updated state.
• Good documentation explains how to use a method and what it produces, not just what each line does.

Three Types of Comments in Java

Comments let you leave notes in your code for yourself and other programmers. They explain intent and usage, but they do not change how the program runs because the compiler skips over them.

Single-line comments //

Everything after // on that line is a comment.

</>Java
int score = 95; // current quiz score

Block comments / /

These can span multiple lines. Everything between /* and */ is ignored.

</>Java
/*
 This section calculates the weighted final grade
 using homework, tests, and participation.
*/

Javadoc comments / /

Javadoc comments start with /** and are used to create API documentation, the same kind of documentation you read when learning how to use a library class.

</>Java
/**
 * Calculates the final grade for a student based on weighted categories.
 *
 * @param homework the average homework score (0.0 to 100.0)
 * @param tests the average test score (0.0 to 100.0)
 * @param participation the participation score (0.0 to 100.0)
 * @return the weighted final grade as a percentage (0.0 to 100.0)
 */
public double calculateFinalGrade(double homework, double tests, double participation) {
    return homework * 0.3 + tests * 0.5 + participation * 0.2;
}

Tags like @param and @return are common in Javadoc, but for the exam the most important point is knowing that /** */ is the Javadoc style used to generate API documentation.

Preconditions and Postconditions

Preconditions and postconditions describe a method's contract: what it expects before it runs, and what it promises after it finishes.

Preconditions

A precondition is something that must be true just before a method is called for the method to work as intended. The method is not expected to check that the precondition holds. That responsibility falls on the code calling the method.

</>Java
/**
 * Returns the square root of a number.
 *
 * Precondition: x is greater than or equal to 0
 *
 * @param x the value to take the square root of
 * @return the nonnegative square root of x
 */
public double squareRoot(double x) {
    return Math.sqrt(x);
}

If the caller passes a negative value, that breaks the precondition, and the method is not promising correct behavior.

Postconditions

A postcondition is something that must be true after a method finishes running. Postconditions describe the outcome, usually in terms of the value being returned or the updated state of an object's attributes.

</>Java
/**
 * Withdraws money from the bank account.
 *
 * Precondition: amount is positive and does not exceed the balance
 * Postcondition: balance is reduced by amount
 *
 * @param amount the amount to withdraw
 */
public void withdraw(double amount) {
    balance -= amount;
}

Here the postcondition tells callers exactly what changed: the balance went down by the amount withdrawn.

How to Use This on the AP Computer Science A Exam

MCQ

When a multiple-choice question shows a method with documented preconditions and postconditions, treat that documentation as a set of facts you can rely on. If a precondition guarantees an input is valid, you do not need to consider invalid inputs. Use the postcondition to predict the return value or how the object changed.

Free Response

When you write free-response code, read the provided documentation closely before coding. The preconditions tell you what you can assume about the inputs, so you do not waste time writing checks for cases the problem already rules out. The postconditions tell you exactly what your method must return or change to be correct.

Common Trap

Do not assume a method checks its own preconditions. If the documentation states a precondition, the calling code is responsible for meeting it. Writing extra validation the problem did not ask for can cost time and sometimes introduces errors.

Common Misconceptions

• Comments do not slow down or change a running program. The compiler ignores them entirely, so they never execute.
• Javadoc /** */ is not the same as a regular block comment /* */. Javadoc has an extra asterisk and is specifically used to generate API documentation.
• A precondition is not something the method checks for you. It is an assumption the caller must satisfy before calling.
• A postcondition is not a guarantee for every possible input. It only holds when the preconditions were met first.
• Documentation is not just restating each line of code. Good documentation explains how to use the method and what result to expect.

Related AP Computer Science A Guides

• 1.4 Assignment Statements and Input
• 1.14 Calling a Void Method
• 1.6 Compound Assignment Operators
• 1.9 Calling a Void Method With Parameters
• 1.1 Why Programming? Why Java?
• 1.11 Using the Math Class