# AP® Computer Science A 1.8 Documentation with Comments Source: https://lockincs.com/ap-csa/unit-1/1-8-documentation-with-comments/ Last reviewed against the College Board Course and Exam Description (CED): 2026-11-12 CED codes: 1.8.A, 1.8.A.1, 1.8.A.2, 1.8.A.3 Comments explain code to programmers and are ignored by the compiler. Java has three types: // for one line, /* */ for a block and /** */ for Javadoc comments that create API documentation. A precondition must be true before a method runs; a postcondition must be true after it runs. ## What you will learn - 1.8.A Describe the functionality and use of code through comments. ## 1\. Comments and their three types Comments are written for both the original programmer and other programmers, to help them understand the code and what it does. Comments are ignored by the compiler and are not executed when the program runs 1.8.A.1. The 3 types of comment in Java 1.8.A.1: | Comment | Use | | --- | --- | | `// text` | one line | | `/* text */` | a block over several lines | | `/** text */` | Javadoc: used to create API documentation | ``` /* Scoreboard: adds the points for one round. Written for the class quiz game. */ int points = 40; // points before this round points += 15; // points = 0; this line is a comment, so it never runs System.out.println(points); ``` Output: ``` 55 ``` The line `// points = 0;` looks like code, but it is a comment, so the compiler ignores it. ## 2\. Preconditions A **precondition** is a condition that must be true just before a method runs, in order for it to behave as expected. There is no expectation that the method will check that its preconditions are satisfied 1.8.A.2. It is the caller’s job to meet them. ## 3\. Postconditions A **postcondition** is a condition that must always be true after a method runs. Postconditions describe the outcome of the method: what is returned, or the current values of the object’s attributes 1.8.A.3. Both conditions are often written in a Javadoc comment above the method: ``` /** Returns the average score: total divided by count. * Precondition: count > 0 * Postcondition: returns the average (total divided by count) as a double */ public static double average(int total, int count) { return (double) total / count; } // in main System.out.println(average(170, 2)); System.out.println(average(10, 4)); ``` Output: ``` 85.0 2.5 ``` What if a caller breaks a precondition? This method shares points equally. It does not check `people`, so with 0 its behavior is not what anyone wants: ``` /** Returns each person's share of the points. * Precondition: people > 0 * Postcondition: returns total divided by people (int division) */ public static int share(int total, int people) { return total / people; } // in main System.out.println(share(90, 4)); System.out.println(share(90, 0)); ``` Output: ``` 22 Exception in thread "main" java.lang.ArithmeticException: / by zero ``` The first call meets the precondition and returns 22. The second call breaks it, so the program stops with an `ArithmeticException`. The fault belongs to the caller who broke the precondition, not to the method. **Watch out:** if a call breaks a precondition, the method’s behavior is not guaranteed. It is the caller’s job, not the method’s, to meet it. ## Common mix-ups - Not true: A method checks its own preconditions and reports a problem. There is no expectation that the method will check its preconditions. Meeting them is the caller's job; if they are broken, the method's behavior is not guaranteed. - Not true: Comments slow the program down. Comments are ignored by the compiler and are not executed when the program runs. - Not true: A postcondition is what must be true before a method runs. That is a precondition. A postcondition must always be true after the method runs: it describes what is returned or the values of the object's attributes. ## In 30 seconds - Comments help the original programmer and other programmers understand the code; the compiler ignores them. - // is a one-line comment, /* */ is a block comment, /** */ is a Javadoc comment used to create API documentation. - A precondition must be true just before a method runs for it to behave as expected; the method is not expected to check it. - A postcondition must always be true after the method runs; it describes what is returned or the values of the object's attributes. ## Checkpoint: 4 practice questions ### Question 1 A method's documentation says `Precondition: num > 0`. A programmer calls the method with `num` equal to 0. Which is true? - A. The method will check `num` and print an error message. - B. The method is not expected to check the precondition, so its behavior is not guaranteed. - C. The compiler will report a syntax error. - D. Java changes `num` to 1 before the method runs. **Answer: B.** The method is not expected to check preconditions; meeting them is the caller's job. A is wrong because no check is promised. C is wrong because the compiler does not read comments or know the run-time value of `num`. D is wrong because Java never changes an argument to meet a precondition. ### Question 2 Consider the following code segment. What is printed? ```java int count = 3; // count = 10; /* count = 20; */ count = count * 2; System.out.println(count); ``` - A. 6 - B. 20 - C. 40 - D. 10 **Answer: A.** Comments are ignored by the compiler and never run, so only `count = 3` and `count = count * 2` execute, giving 6. B (20) runs the one-line comment as code (10 * 2). C (40) runs the block comment as code (20 * 2). D (10) takes the value in the one-line comment and skips the multiplication. ### Question 3 Which type of comment is used to create API documentation? - A. `// comment` - B. `/* comment */` - C. `/** comment */` - D. `` **Answer: C.** `/** */` comments are Javadoc comments, used to create API documentation. A is a one-line comment and B is a block comment; both are ignored without producing documentation. D is not a Java comment at all, so it does not compile. ### Question 4 Consider the following documentation for a method of a `BankAccount` class. A call `deposit(50)` meets the precondition. Which of the following is guaranteed after the call? ```java /** Precondition: amount > 0 * Postcondition: the balance has increased by amount */ public void deposit(int amount) ``` - A. The method has checked that amount is positive. - B. The method returns the new balance. - C. The method prints the new balance. - D. The balance is 50 more than before the call. **Answer: D.** A postcondition must always be true after the method runs; here it says the balance increased by `amount`, which is 50. A is wrong because methods are not expected to check preconditions. B is wrong because the method is void, so it returns nothing. C is wrong because the documentation says nothing about printing. ## Questions students ask **What are the three types of comments in Java?** // starts a comment that runs to the end of the line, /* */ encloses a block comment over several lines, and /** */ is a Javadoc comment, used to create API documentation. **What is a precondition in Java?** A precondition is a condition that must be true just before a method runs for the method to behave as expected. The method is not expected to check it; the caller must make sure it is true. **What is a postcondition?** A postcondition is a condition that must always be true after a method runs. It describes the outcome, such as the value returned or the current values of the object's attributes. --- © LockInCS, licensed CC BY-NC-ND 4.0. AP® is a trademark registered by the College Board, which is not affiliated with, and does not endorse, this website.