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 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. Precondition: Precondition goes here Postcondition: Postcondition goes p1 A description of this p2 A description of this 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