Hands on Testing Java

Writing Javadoc Comments

Javadoc for a class, a driver, a computation method, a test-case method, and an instance variable.

Writing Javadoc Comments for a Class

Include the following bits of data in your Javadoc comment for every class:

1. Describe why the class exists. Is it a driver? a test-case class? a computation class?
2. Describe some of the highlights of the class (if there are any).
3. Include your name, the name of the course (e.g., CS 108), and the assignment that you've written the class for (e.g., Lab #7).

Writing Javadoc Comments for a Driver

Be sure to add Javadoc comments to the class itself as normal. Then add a Javadoc comment to main():

1. Describe briefly what the driver does. Perhaps refer to the class where the computation method comes from.
2. Describe the nature of the input from the keyboard (or file).
3. Describe the nature of the output to the screen (or file).
4. Do not bother with @return or @param tags (unless you're using the args parameter).

Example:

/**
 * This driver reads in a number and squares it.  Input (keyboard): an
 * integer; output (screen): the integer squared.
 */
public static void main(String[] args) {
  Keyboard theKeyboard = new Keyboard();
  Screen theScreen = new Screen();
  theScreen.print("Enter an integer: ");
  int number = theKeyboard.readInt();
  theScreen.println(number + " squared is " + (number*number) + ".");
}

Writing Javadoc Comments for a Computation Method

Be sure to add Javadoc comments to the class itself as normal. Then add a Javadoc comment to the method:

1. Describe briefly what the method computes.
2. Describe any pre- or post-conditions.
3. Describe the parameters using @param tags.
4. Describe the return value using the @return tag.
5. Describe the thrown exceptions using the @throws tag.

Example:

/**
 * This method squares a number.  The square is returned.
 * Precondition: the value received must be positive.
 * @param n the number to be squared.
 * @return the square of the number.
 * @throws IllegalArgumentException when the parameter is negative.
 */
public int square(int n) {
  if (n < 0)
    throw new IllegalArgumentException(n + " is negative.");
  return n*n;
}

Writing Javadoc Comments for a Test Method

1. Describe briefly what the method the test method tests.

Example:

/**
 * This method tests @link SillyMath#square(int).
 */
public void testSquare() {
   assertEquals(9, SillyMath.square(3));
   ...
}

Write Javadoc Comments for an Instance Variable

1. Describe briefly what the value in the variable represents.

Example:

/**
 * The x-coordinate of a point.
 */
private double myX;