1.8 Documentation with 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.