Contract

Decide what kind of information the function needs from the outside world, and what kind of information it returns to the outside world. Ask the following questions:

1. How many pieces of information (parameters) does it need to be given in order to do its job?
2. What kind(s) of information are the various parameters? (At first, the only kinds of information we know about are ints and Strings.)
3. What kind of information, if any, does it return as a value?

You can write this information down as a simple Java comment:

/**
 * cube: find the third power of a number.
 * Takes in an int and returns another int
 */

/**
 * howOld : produce a formatted message showing a person's name and how
 * old (s)he is.
 * Takes in a String (the person's name) and an int (the age)
 * and returns a String of the form "Joe Schmoe is 21 years old."
 */

However, you are encouraged to write it down in a standard format called "javadoc" format. BlueJ gives you the beginnings of this automatically when you create a new class or method, and BlueJ "understands" this format and can generate automatic Web documentation for you. Here are the same two examples in javadoc form:

/**
 * cube : find the third power of a number.
 *
 * @param    num   the int to be cubed
 * @return   the number num^3, which is also an int
 */

/**
 * howOld : produce a formatted message showing a person's name and how
 * old (s)he is.
 *
 * @param    name   a String indicating the person's name
 * @param    age    an int indicating the person's age in years
 * @return   a String, something like "Joe Schmoe is 21 years old."
 */