Aim for FiveComputer Science A

Unit 1 · Topic 1.8

1.8 Documentation with Comments

Comments explain code to people, and preconditions and postconditions are the promises a method makes about how it should be used. You'll read preconditions in almost every free-response question, so you need to know what they let you assume.

Key terms

  • comment
  • Javadoc
  • precondition
  • postcondition

Three kinds of comments

A comment is text in your code that the compiler ignores. It's never run. Comments are for people: you, months later, or another programmer trying to understand what the code does.

  • // starts a comment that runs to the end of the line.
  • /* and */ surround a block comment, which can span many lines.
  • /** and */ surround a Javadoc comment, placed just before a class or method. Tools read Javadoc comments to build API documentation, the kind of documentation you met in 1.7.

All three in action

/** * Returns how many items each person gets * when total items are shared equally. * Precondition: people > 0 * Postcondition: returns total / people; * total and people are unchanged. */ public static int perPerson(int total, int people) { // integer division drops any leftovers return total / people; } /* Shared by any method that needs the class size. */ public static int classSize = 28;

Calling perPerson(17, 5) returns 3, and perPerson(classSize, 4) returns 7. The comments change nothing about how the code runs.

Preconditions

A precondition is something that must be true right before a method is called for the method to work as described. Above, the precondition is that people is greater than 0.

The key idea: the method does not check its precondition. It's the caller's job to meet it. If someone calls perPerson(12, 0) anyway, the method divides by zero and throws an ArithmeticException.

On free-response questions, this works in your favor. If a precondition says a list has at least one element, or a parameter is positive, you can assume it's true. You don't need to write code to check it.

Postconditions

A postcondition is something that will always be true after the method finishes, as long as the precondition was met. It describes the outcome: what the method returns, or how the object's attributes have changed.

For example, a method called deposit(int amount) might have the postcondition "the account balance has increased by amount". A method that returns a value might have the postcondition "returns the largest value in the list; the list is unchanged".

Together, preconditions and postconditions describe a method completely from the outside: what you must provide and what you get back. That's procedural abstraction in action (see 1.9).

Worked examples

Try each one yourself first, then open the solution.

  1. Example 1

    What happens when a precondition is broken

    Using perPerson from above (precondition: people > 0), what happens when this code runs?int a = perPerson(20, 3); int b = perPerson(0, 4); System.out.println(a + " " + b); int c = perPerson(12, 0);

    Show the solution
    1. Step 1: perPerson(20, 3) meets the precondition. It returns 20 / 3, which is 6 with integer division.
    2. Step 2: perPerson(0, 4) also meets it, since people is 4. Zero items shared by 4 people is 0 each.
    3. Step 3: The print shows 6 0.
    4. Step 4: perPerson(12, 0) breaks the precondition. The method doesn't check, so it divides 12 by 0, and Java throws an ArithmeticException.

    Answer: It prints 6 0, then the last call throws an ArithmeticException because it broke the precondition.

Common mistakes

  • Thinking a method checks its own precondition. It doesn't have to; breaking the precondition can give wrong results or an exception.
  • Writing extra code in a free-response answer to check a precondition that's guaranteed. It wastes time. (A correct check usually won't cost points, but a wrong one can.)
  • Mixing up the two: preconditions are about before the call, postconditions about after it.

On the exam

  • Multiple-choice questions may ask which precondition a method needs to work as intended, for example that an index is in range or a divisor isn't zero.
  • Read every precondition in a free-response question before you write code. Each one is something you can rely on, which often makes the code shorter.

Connected topics

Videos

Check yourself

3 questions on 1.8 Documentation with Comments. Pick an answer to see if you got it, and why.

Question 1 of 3

Each of the following lines is the only statement in a main method. Which one causes a compile-time error?

Question 2 of 3

Consider the following method./** * Returns the number of digits in num. * Precondition: num > 0 */ public static int countDigits(int num) { int count = 0; while (num > 0) { num /= 10; count++; } return count; }Which of the following statements about the precondition is true?

Question 3 of 3

Consider the following method header and comment./** * Postcondition: returns a value that is greater than or equal to 0 * and less than limit. */ public static int wrap(int value, int limit)Assuming any precondition is met, which of the following must be true about the value returned?

0 of 3 answered