Method Comment Blocks

Every method should begin with a method comment block. The method comment block contains - at a minimum - the name of the method, a list of arguments that it receives, a description of its return value (if any), and a brief description of what the method does. In addition, any side-effects (or outputs) performed by the method should be documented.

The following is an example function comment block.

    * name:  isVowel
    * parameters:  char -- a character
    * returns:  true if parameter value is vowel; false otherwise
    * description:  This method tests to see if a character is a
    *               the vowel (a, e, i, o, u).  The character can
    *               be either upper- or lower-case.

Cay Horstmann quote.

"The description of a method comment block does not document the implementation but the idea."