Required JavaDoc Tags

Javadoc Documentation Hard Copy

Learn Javadoc Tutorials

Customize @pre, @post, and @invariant With UBC Taglets

  1. Every class and interface should have the following tags where applicable.

    @author [author name]author's name of the class/interface
    @version [version]version information of the class/interface
    purpose [rationale for existing]the reason that the class/interface exists.
    @invariant [condition] an assertion that is always true at a particular point in an algorithm

  2. Methods and constructors should have the following tags where applicable.

    @pre [condition] precondition that must exist at the beginning of a method in order for the method to work correctly
    @post [condition] postcondition existing after a method has finished executing
    @param [argument name] [argument description]describes an argument
    @return [description of return]data returned by a method. Constructors never return data.
    @exception [exception thrown] [exception description]exception thrown by a method

  3. It is not necessary to document simple accessor and mutator methods.

    A simple accessor method returns a primitive or String and not a non-String object [ eg: int getNum( ) ].

    A simple mutator method receives a primitive or String and not a non-String object [ eg: void setNum(int value) ].

    Do document accessor and mutator methods that receive or return an object other than a String.

    Do document accessor methods that return a "magic number" [ eg: public static int size( ) returning the number of bytes in a record ].


URL:   http://www.comscigate.com/    Last Revised:  November 4, 2007