Understanding Design by Contract and Javadoc in Java Programming
Design by Contract is a fundamental concept in Object Oriented Programming that emphasizes clear specifications before module implementation. This involves defining preconditions, purpose, and postconditions. For instance, a Queue class's dequeue method requires the queue to be instantiated and ensures state changes after execution. Java's Javadoc tool enhances documentation by allowing developers to write structured comments, which describe classes, methods, and parameters. By following Javadoc conventions, programmers can generate comprehensive HTML documentation easily.
Understanding Design by Contract and Javadoc in Java Programming
E N D
Presentation Transcript
Documentation Javadocs
Recall 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
Recall 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
