Documentation

Javadocs

Design/Documentation• An essential ingredient of good Object Oriented

programming is known as design by contract.

• This means that before modules are written a specification or contract is written which states

• What preconditions must be met for the module to properly function

• What is the purpose of the module

• What will be the state of things after the module executes which is known as the postconditions

Example

• A module located in a Queue class which will dequeue the element at the head of the queue.

• Precondition– The queue must be instantiated. It is recommended that

isEmpty be run to assure that their is an element to dequeue• Purpose

– Remove the element at the head of the queue and return it to the user. It will be an Object.

• Postcondition– The queue will have one fewer element unless the queue was

empty to start with in which case the method will return null and the queue will be unchanged

Design/Documentation• Java comes with an excellent documentation tool

called Javadoc

• Usage of the Javadoc system requires following several steps

• First special Javadoc block comments are added to source files.

• Javadoc block comments start with /** and end with */ this they function like regular comments

• Each class, field and method should be commented with a Javadoc comment just before the actual item.

Javadoc• The comment should start with a short descriptive

phrase followed by a period .• Then a longer description of the purpose of the item

may be added.• HTML may be embedded• Special tags can be used such as

@author@revision@parameter@return

• The precondition and postcondition should be included.

Javadoc• Once commenting is complete the Javadoc program is

run from the OS prompt.

• If for example a group of class files for a given project are located in the same directory then Javadoc may be run by typing

javadoc *.java

• When the program runs it will report any problems and will produce a series of HTML files documenting all classes, methods and fields.

• A Javadoc template is on the next slide followed by a sample

Javadoc Template/* -------------------------------------------------*//** Descriptive phrase. Longer statement of purpose. <BR><B>Precondition:</B> Precondition goes here <BR><B>Postcondition:</B> Postcondition goes here @param p1 A description of this parameter @param p2 A description of this parameter @ return A description of the return value */ public int someMethod(double p1, String p2) {

return 0; }

Note: The leading comment of “---” characters is not part of the Javadoc system but will make code easier to read

Results

Results