Documentation with Comments

Open a program you wrote two months ago and you may not remember why a line says quizScore += bonus or what the 2 in int bonus = 2; stands for. Now imagine reading a program someone else wrote. Java code says exactly what the computer does, but it rarely says why. The reasons live in the programmer’s head, and nobody else can see them.

The fix is to write the reasons down, right next to the code, in plain English. Java gives you a way to do this so the compiler does not try to read your English as Java. In Topic 1.1 you saw that the compiler checks every line and translates it before the program runs. Text marked as a note is skipped by the compiler entirely: it is never checked, never translated, and never run.

A comment is text in a program that is written for people to read. Comments help the original programmer (you, later) and other programmers understand what the code does and why. The compiler ignores comments, so they are not part of the running program at all.

The quickest kind of comment starts with two slashes, //: everything from // to the end of that line is a comment. (1.8.2 looks at this kind closely.)

public class ScoreReport
{
    public static void main(String[] args)
    {
        int quizScore = 18;
        int bonus = 2;
        quizScore += bonus;
        System.out.print("Final quiz score: ");
        System.out.println(quizScore);
    }
}

Final quiz score: 20

public class ScoreReportCommented
{
    public static void main(String[] args)
    {
        // Points earned on the quiz, out of 20.
        int quizScore = 18;
        // Extra credit for showing all work.
        int bonus = 2;
        // The bonus may push the score above 20. That is allowed.
        quizScore += bonus;
        System.out.print("Final quiz score: ");
        System.out.println(quizScore);
    }
}

Final quiz score: 20

Now change one thing: put a Java statement inside a comment. Programmers do this on purpose to switch a line off without deleting it, which is called commenting out the line.

int tickets = 3;
// System.out.println("Checking tickets...");
tickets *= 2;
System.out.println(tickets);

6

Line 2 is a perfectly good println statement, but it sits after //, so the compiler treats it as a note and the program never prints Checking tickets.... Only line 4 prints, showing tickets after it was doubled. The rule depends on where the text is, not on what the text looks like: anything inside a comment is ignored, even if it is valid Java.

int score = 80;
// Add 10 bonus points.
score += 5;
System.out.println(score);

85

int laps = 4;
// laps += 3;
laps *= 2;
// System.out.println(laps);
laps -= 1;
System.out.println(laps);

7

Most notes a programmer needs are short: what a variable stands for, the units of a number, why a step is there. For those, a whole paragraph is too much. You want a note that fits on one line, sometimes on the same line as the code it explains.

A single-line comment starts with // and ends at the end of that line. It can take up a whole line by itself, or it can come after code on the same line, which is called an end-of-line comment.

// A whole-line comment: the entire line is a note.
int count = 3;   // An end-of-line comment: the code runs, the note does not.

Take the second line apart:

• int count = 3; comes before //, so it is ordinary code. The compiler translates it and it runs.
• // marks where the comment begins.
• An end-of-line comment: ... runs to the end of the line and is ignored.

There is no closing marker. The end of the line ends the comment, so the next line is code again.

double price = 4.5;   // price of one smoothie, in dollars
int count = 3;        // smoothies ordered
double total = price * count;   // 3 times 4.5
System.out.println(total);

13.5

Now vary the order on a line. In int pages = 320; // number of pages, the code comes first and runs. Flip it, and the code is gone:

public class CommentSwallowsCode
{
    public static void main(String[] args)
    {
        // number of pages in the book int pages = 320;
        System.out.println(pages);
    }
}

CommentSwallowsCode.java:6: error: cannot find symbol
        System.out.println(pages);
                           ^
  symbol:   variable pages

int pages = 320; // number of pages in the book
System.out.println(pages);

int stamps = 12; // stamps in the album stamps += 6;
System.out.println(stamps);

int stamps = 12; // stamps in the album
stamps += 6;
System.out.println(stamps);

Sometimes a note needs several lines: a description of what a whole program does, or a few sentences about how a tricky step works. You could start every line with //, but there is a tool made for longer notes.

A block comment starts with /* and ends with */. Everything between the two markers is a comment, no matter how many lines it covers. Unlike //, the end of a line does not end a block comment; only */ does.

/*
 * GardenOrder
 * Works out how many seed packets to buy for a garden.
 * Each row of the garden needs 4 packets.
 */
public class GardenOrder
{
    public static void main(String[] args)
    {
        int rows = 6;
        int packets = rows * 4;
        System.out.println(packets);
    }
}

24

Now use a block comment for a different job: switching off several lines at once.

int rows = 6;
/*
rows += 2;
System.out.println("Added two rows");
*/
int packets = rows * 4;
System.out.println(packets);

24

Lines 3 and 4 are valid statements, but they sit between /* on line 2 and */ on line 5. Neither runs: rows stays 6 (not 8), Added two rows is never printed, and the output is still 24. Commenting out four lines with // would take four markers; a block comment takes one pair.

public class UnclosedComment
{
    /*
     * Prints a reminder before the test.

    public static void main(String[] args)
    {
        System.out.println("Bring a calculator!");
    }
}

UnclosedComment.java:3: error: unclosed comment
    /*
    ^

Here are the two kinds of comments so far, side by side:

int coins = 10;
/* coins += 5;
coins *= 2; */ coins -= 3;
System.out.println(coins);

7

In Topic 1.7 you learned that a library’s documentation tells you what its classes can do: the methods of String and Math, what each one needs, and what each one gives back. Someone had to write those pages. Writing them separately from the code would be risky, since the pages and the code could drift apart. So the people who write a class put the documentation inside the source code, right above each class and method, and a tool builds the pages from it.

A Javadoc comment starts with /** (a slash and two stars) and ends with */. It is written directly above a class or a method and describes it. To the compiler, a Javadoc comment is just another comment and is ignored. But a separate tool that comes with Java, called javadoc, reads every /** */ comment in a class and turns them into the documentation pages, known as the API documentation, that programmers read. The String documentation you looked at in Topic 1.7 was built this way from comments in the String class’s source code.

/**
 * A String holds a sequence of characters, such as "Hopper".
 */
public class String
{
    /**
     * Returns the number of characters in this string.
     *
     * @return the number of characters in this string
     */
    public int length()
    {
        // ...the statements that count the characters...
    }
}

A second common tag is @param, which describes a value the method needs to be given. Here is a simplified Javadoc comment for a Math method you will use in Topic 1.11:

/**
 * Returns the absolute value of a: the value without its minus sign.
 *
 * @param a  the number to use
 * @return   the absolute value of a
 */
public static int abs(int a)

The @param line names a, the value that goes in, and says what it is. The @return line says what comes out. (public static can be read past for now; those words are explained in later topics.)

Javadoc comments work in your own programs too. This program has one above the class and one above main:

/**
 * Works out the tip on a restaurant bill.
 */
public class TipCalculator
{
    /**
     * Prints a 20 percent tip on a 45-dollar bill.
     */
    public static void main(String[] args)
    {
        double bill = 45.0;
        double tip = bill * 0.2;
        System.out.println(tip);
    }
}

9.0

The compiler skips lines 1 to 3 and 6 to 8, just as it skips any comment. The program stores 45.0 in bill, computes 45.0 × 0.2 = 9.0, and prints 9.0. The Javadoc comments change nothing about how the program runs; they only give the javadoc tool something to turn into documentation.

All three kinds of comments together:

/**
 * Returns the larger of two values.
 *
 * @param a  one number
 * @param b  another number
 * @return   the larger of a and b
 */
public static int max(int a, int b)

A recipe for bread might say, “Start with the oven heated to 200 °C.” The recipe does not tell you to check the oven; it assumes you already did. If you skip that, the recipe still runs its steps, and you get a pale, raw loaf. Code works the same way: much of it only works if something is already true before it starts.

You have already met a piece of code like that. In Topic 1.5 you rounded a double to the nearest whole number with (int) (x + 0.5), and that trick works only when x is not negative. That “only when” is the idea of this subsection.

A precondition is a condition that has to be true right before a method or a segment of code runs, so that it does what its documentation says. Preconditions are usually stated in a comment. Here is the most important rule about them: the method or code is not expected to check its own precondition. Making sure the precondition is true is the job of whoever uses the code. If the precondition is false, all bets are off: the code may give a wrong answer, or the program may crash.

// Precondition: temperature is not negative.
double temperature = 2.7;
int rounded = (int) (temperature + 0.5);
System.out.println(rounded);

3

// Precondition: temperature is not negative.
double temperature = -2.7;
int rounded = (int) (temperature + 0.5);
System.out.println(rounded);

-2

Breaking a precondition does not always give a quiet wrong answer. Sometimes the program crashes. This segment finds a player’s average points per game:

// Precondition: games is greater than 0.
int totalPoints = 84;
int games = 6;
System.out.println("Computing average...");
int average = totalPoints / games;
System.out.println(average);

Computing average...
14

84 / 6 is 14, so all is well. Now suppose the player has not played yet, so games is 0:

// Precondition: games is greater than 0.
int totalPoints = 84;
int games = 0;
System.out.println("Computing average...");
int average = totalPoints / games;
System.out.println(average);

Computing average...
Exception in thread "main" java.lang.ArithmeticException: / by zero

The first println runs, then line 5 asks Java to divide by zero. As you saw in Topic 1.1, that throws an exception and stops the program, so the average is never printed. (The full message also names the line, and its wording can vary between Java versions.) Again, the code did nothing to protect itself; the precondition comment was the only warning.

Methods in Java’s libraries have preconditions too, written in their Javadoc comments. Here is a simplified version of the documentation for the Math class’s square-root method, which you will use in Topics 1.10 and 1.11:

/**
 * Returns the square root of a.
 * Precondition: a is not negative.
 */
public static double sqrt(double a)

No real number times itself is negative, so a negative number has no square root to give back. The method does not promise to check its precondition for you; if you pass a negative number, you do not get a usable answer. So before you call it, you make sure the argument is not negative. Here it is used correctly. (Math.sqrt(area) calls the method on the value of area; Topic 1.10 explains calls like this fully.)

double area = 49.0;
double side = Math.sqrt(area);
System.out.println(side);

7.0

area is 49.0, which is not negative, so the precondition holds and sqrt gives back 7.0.

// Precondition: temperature is not negative.
double temperature = -4.6;
int rounded = (int) (temperature + 0.5);
System.out.println(rounded);

-4

A precondition tells you what you must do before using some code. The other half of the deal is what the code promises after. When you use Math.sqrt correctly, what exactly do you get? If a method changes something, what will be different when it finishes? Without that promise, you would have to read the method’s code to find out, which is what documentation is meant to save you from.

A postcondition is a condition that is always true after a method or code segment finishes running (as long as its precondition was met). A postcondition describes the result: what value the method gives back, or what the current values of an object’s attributes are afterward. Think of it as the method’s promise. The precondition is your side of the deal; the postcondition is the method’s side.

// Precondition: totalMinutes is not negative.
// Postcondition: hours holds the whole hours in totalMinutes,
// and minutes holds the leftover minutes, from 0 to 59.
int totalMinutes = 135;
int hours = totalMinutes / 60;
int minutes = totalMinutes % 60;
System.out.print(hours);
System.out.print(" h ");
System.out.print(minutes);
System.out.println(" min");

2 h 15 min

Now vary the input to test the edge of the promise: use 59 minutes, which is less than one hour. Changing line 4 to int totalMinutes = 59; prints:

0 h 59 min

59 / 60 is 0 and 59 % 60 is 59. The postcondition still holds: 0 whole hours, and 59 leftover minutes, which is in the 0 to 59 range. A good postcondition holds for every input that meets the precondition, not just typical ones.

Postconditions appear in Javadoc comments too. In the String sketch from 1.8.4, the line “Returns the number of characters in this string” is a postcondition stated in terms of what is returned: after length runs, you are guaranteed a count of the characters. The sqrt method’s documentation promises that it returns the square root of a.

A postcondition can also describe an object’s attributes (from Topic 1.7, the data a class keeps in variables). Here is the documentation for a method in an invented BankAccount class, whose attribute is the account’s balance. The rest of the header is taught in Topic 1.9; for now, focus on the comment.

/**
 * Adds money to this account.
 * Precondition: amount is greater than 0.
 * Postcondition: the balance has gone up by amount.
 */
public void deposit(double amount)

This method does not give back a value. Its promise is about the attribute: when it finishes, the balance is larger by exactly amount.

// Precondition: totalMinutes is not negative.
// Postcondition: hours holds the whole hours in totalMinutes,
// and minutes holds the leftover minutes, from 0 to 59.
int totalMinutes = 200;
int hours = totalMinutes / 60;
int minutes = totalMinutes % 60;
System.out.print(hours);
System.out.print(" h ");
System.out.print(minutes);
System.out.println(" min");

3 h 20 min

This complete program uses all three kinds of comments and documents a precondition and a postcondition. Before reading the walkthrough, find each comment and decide which kind it is.

/**
 * Splits pizza slices evenly among friends.
 */
public class PizzaShare
{
    /**
     * Prints each friend's share and the slices left over.
     */
    public static void main(String[] args)
    {
        /*
         * Precondition: friends is greater than 0.
         * Postcondition: each friend's share and the leftover
         * slices have been printed, and leftover is less than friends.
         */
        int slices = 16;   // 2 pizzas, 8 slices each
        int friends = 5;

        int perFriend = slices / friends;   // whole slices only
        int leftover = slices % friends;

        System.out.print("Each friend gets ");
        System.out.println(perFriend);
        // System.out.println("Enjoy!");
        System.out.print("Slices left over: ");
        System.out.println(leftover);
    }
}

Each friend gets 3
Slices left over: 1

The comments.

The run. The compiler skips every comment, leaving the statements on lines 16, 17, 19, 20, 22, 23, 25, and 26.

Checking the conditions. The precondition held, since 5 is greater than 0. So the postcondition must be true, and it is: both values were printed, and the leftover (1) is less than the number of friends (5). If there were 5 or more slices left over, everyone could have had one more, so the division would have been wrong.

Breaking the precondition. If line 17 were int friends = 0;, the precondition would be false. Nothing in the program checks for that. Line 19 would divide by zero, Java would throw an ArithmeticException, and the program would stop before printing anything. The precondition comment is what tells the next programmer to make sure friends is never 0.

• Comments are notes written for the original programmer and for other programmers. The compiler ignores them and they never run, so they never change a program’s output; code inside a comment (commented out) does not run either.
• // makes a comment that ends at the end of its line. /* */ makes a block comment that can cover many lines and ends only at */.
• /** */ makes a Javadoc comment. Written above a class or method, it describes it, and the javadoc tool turns these comments into API documentation like the pages for String and Math. Tags such as @param and @return describe what goes in and what comes out.
• A precondition is what must be true before a method or code segment runs. The code does not check it; the user is responsible, and breaking it can cause a wrong result or a crash.
• A postcondition is what is guaranteed to be true afterward, described in terms of the value returned or the values of the object’s attributes.

/**
 * Keeps count of the books a student has read.
 */
public class ReadingLog
{
    public static void main(String[] args)
    {
        int books = 2; // read in September
        /* books += 4;  read in October
           books += 1; */
        books *= 3; // books -= 1;
        // books += 10;
        System.out.print("Books: ");
        System.out.println(books);
    }
}

Books: 6

int water = 5; // cups of water so far
/* Each glass holds 2 cups.
   The student drinks 3 more glasses.
water += 2 * 3; */
System.out.println(water);

int water = 5; // cups of water so far
/* Each glass holds 2 cups.
   The student drinks 3 more glasses. */
water += 2 * 3;
System.out.println(water);

/**
 * Works out the total cost of an order of tickets.
 * Precondition: quantity is greater than 0, and priceCents is not negative.
 * Postcondition: returns quantity times priceCents.
 */
public static int totalCost(int quantity, int priceCents)

// Precondition: totalMinutes is not negative.
// Postcondition: hours holds the whole hours in totalMinutes,
// and minutes holds the leftover minutes, from 0 to 59.
int totalMinutes = -135;
int hours = totalMinutes / 60;
int minutes = totalMinutes % 60;
System.out.print(hours);
System.out.print(" h ");
System.out.print(minutes);
System.out.println(" min");

-2 h -15 min

int perBox = cookies / boxes;

Check each statement. If the answer is “not yet,” reread the linked subsection.

• I can explain who comments are for and why they never change what a program prints. Reread
• I can tell which part of a line is code and which part is a // comment. Reread
• I can find where a /* */ block comment starts and ends, even in the middle of a line. Reread
• I can explain how /** */ comments become API documentation and read @param and @return. Reread
• I can state a precondition and explain that the caller, not the code, must make it true. Reread
• I can state a postcondition and tell it apart from a precondition. Reread