Commenting Methods

The COMP1010 site describes how user-defined methods need to be commented for assignments.

Every method (except main) must begin with a prologue comment, similar to the following:

/**
 * Describe the purpose of the method. Clearly.
 *
 * @param firstParameter  description of what firstParameter means
 * @param secondParameter description of what secondParameter means
 *                        and so on, for all the parameters...
 *
 * @return                what is the meaning of the return value?
 */

Parts of the prologue may be omitted if appropriate, e.g. if the method has no parameters. 

A complete comment block describes the method, explains the parameters, and states what the return value means. Using this standard commenting format provides two benefits:

1. The person marking your assignment can see what your method does at a glance.
2. Anyone who calls your method has all the information they need to use your method.

Here's an example of a comment block for a temperature converting method:

/**
 * This method converts a Fahrenheit temperature to a Celcius temperature
 *
 * @param fahrenheitTemp - The Fahrenheit temperature to convert into Celcius
 *
 * @return double celciusTemp - The calculated Celcius temperature
 */
public static double convertToCelcius(double fahrenheitTemp)
{
    double celciusTemp;
    celciusTemp = (fahrenheitTemp - 32) * 1.8;
    return celciusTemp;
}

Now imagine that you want to convert temperatures, but you do not know the formulas for doing so. If you have access to the above method, you only need to know what the method does and not how it does it. The comment block allows you to see the what without reading the code.