Java, Java, Java 3E

Documentation Specifications

We will be using javadoc comments to describe classes, methods and files. A javadoc comment begins with /** and ends with */ and is ignored by the compiler. Special tags, such as the @author tag, are used by the javadoc program to generate HTML documentation for a Java source program. In this course we will use the following tags, as exemplified in the sample program: @author, @param, @return.

Here are the documentation specifications that should be followed in documenting all labs and programming assignments.

• There should be a comment block at the beginning of the program indicating the name of the program's file, the program's author (your name), today's date and a brief description of what the program does. This comment block should conform to the following format:

       /**  ***************************************************
       file: NumberTester.java                               
       date:  September 27,2001                           
       @author cpsc115 staff                           
       course: cpsc 115 -- spring 2002
       description: This class stores a integer and determines
          whether it is odd or even.
       ********************************************************
       */
  

• Variable names and other identifiers in the program should be given names that are suggestive of their use or purpose. For example, year is a more descriptive choice for a variable name than y. The only place that single letter variable names are permitted is as parameters or as loop variables.
• Where appropriate, declarations and executable statements should be commented to indicate their effect or purpose. It is not necessary to comment every line, only those statements that are not obvious.
• The closing brackets (}) of classes, methods and other large blocks of code should be commented with the name of the method or class or code block to indicate what code block is being ended. See the sample program for examples.
• There should be a comment block at the beginning of each method definition that describes what the method does and what data is input to the method through its parameters and what data is returned by the method through its return value. These comment blocks should make use of javadoc's @param and @return tags as follows:

   /**
    * Converts its int parameter into a String
    * @param -- an integer value, n, is input to this method
    * @return -- this method returns a String representation of n
    */
    public String convertN( int n ) {
      return n + "";
    } // convertN()