1. Comments¶

Note

You can extract documentation from your source code, and generate well-formatted HTML pages, using a tool called Javadoc. That way, you can write documentation as you go, and as things change, it is easier to keep the documentation consistent with the code. The Javadoc tool is included with the Java compiler, and it is widely used. In fact, the official documentation for the Java library (https://docs.oracle.com/javase/8/docs/api/) is generated by Javadoc. This can be a useful place to learn about code that has already been written that you can use in your programs.

Javadoc scans your source files looking for Javadoc comments. They begin with /** (two stars) and end with */ (one star). Anything in between is considered part of the documentation.

Here’s a class definition with two Javadoc comments, one for the Goodbye class and one for the main method:

Run the code (triangular button above “Goodby.java”), and notice how the comments do not impact the execution of the program. The class comment explains the purpose of the class. The method comment explains what the method does.

Click the pencil icon next to the triangular run-button above to get back to the code. Notice that this example also has an inline comment //. In general, these comments are short phrases that help explain complex parts of a program. They are intended for other programmers reading and maintaining the source code.

In contrast, Javadoc comments are longer, usually complete sentences. They explain what each method does, but they omit details about how the method works. And they are intended for people who will use the methods without looking at the source code.

Appropriate comments and documentation are essential for making source code readable. And remember that the person most likely to read your code in the future, and appreciate good documentation, is you.

Note

Javadoc tags

It’s generally a good idea to document each class and method, so that other programmers can understand what they do without having to read the code.

To organize the documentation into sections, Javadoc supports optional tags that begin with the at sign @. For example, we can use @author and @version to provide information about the class. For example:

/**
 * Utility class for extracting digits from integers.
 *
 * @author Chris Mayfield
 * @version 1.0
 */ public class DigitUtil {

Documentation comments should begin with a description of the class or method, followed by the tags. These two sections are separated by a blank line (not counting the *).

When we get to implementing our own methods, we will use @param and @return to provide information about parameters and return values. We will learn about what these actually mean soon, but knowing what a method’s parameters and return type is very useful for Java programming.

/**
 * Tests whether x is a single digit integer.
 *
 * @param x the integer to test
 * @return true if x has one digit, false otherwise
 */ public static boolean isSingleDigit(int x) {

The figure below shows part of the resulting HTML page generated by Javadoc. Notice the relationship between the Javadoc comment (in the source code) and the resulting documentation (in the HTML page).