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. 

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 celciusTemp - The calculated Celcius temperature
 */
public static double convertToCelcius(double fahrenheitTemp)
{
    double celciusTemp;
    celciusTemp = (fahrenheitTemp - 32) * 1.8;
    return celciusTemp;
}