Documenting Advanced Programming Techniques

Transcription

1 Documenting Advanced Programming Techniques Prof. Dr. Bernhard Humm FB Informatik, Hochschule Darmstadt 1

2 Agenda 1. Documenting with JavaDoc 2. Quick check 2

3 JavaDoc generates HTML from Java code comments /** A stack of integers. * This is a FIFO data structure * storing integers in a stack-like way. Donald Knuth */ public class Stack { } /** The elements in the stack. */ private int[] data;... /** Push an integer on the stack. * If the stack is full * x new element */ public void push (int x) {... }... 3

4 Precise and complete method documentation class List { public: /** * Adds a new value to the list. * value to be added * multiple occurrences in list are allowed */ void add(int value); One sentence which describes the purpose of the method (more sentences if needed) Precise description of input parameters (method arguments) Signature 4 /** * Removes a value once from the list. * value to be removed - further occurrences remain in list true if one occurrence was removed, * false if value was not in list */ boolean remove(int value); }; Precise description of return value. No implementation details (Loops etc.)! Potentially description of exceptions and conditions in which they are thrown.

5 NetBeans support 1. Implement signature 2. Press /** <Enter> 3. NetBeans complements comment with parameters 4. Complete comment 5

6 Class documentation One sentence which describes the purpose of the class(more sentences if needed) /** A stack of integers. * This is a FIFO data structure * storing integers in a stack-like way. * Bernhard G Humm <Bernhard.humm@h-da.de> */ public class Stack Oracle documentation conventions: 6

7 JavaDoc <Author name> (classes and <Version number> (classes and <parameter name> <description> (Methods and <Return value description> <Exception class> <description> (Methods)

8 What to document? The client s view! (public methods and interfaces) import import Client (service consumption) // Declaration, configuration I i = new C(); // Usage i.m(); Interface public interface I { public void m (); } Implementation (service provision) public class C implements I { public void m() { } } 8

9 Document the interface specification Interface Name Operationen Signatur Semantik Interface name public interface OrderManager { Return type Operation name Input parameter and type Order placeorder (Customer c, Article a) throws NotAvailableException; } Pre-conditions, post-conditions, etc. (text) Exception Nicht-funktionale Eigenschaften Protokoll Text Text, sequence diagrams, etc. 9

10 Example Accounting 10

11 Details Accounting 11 Semi-formal notation similar to QSL [Siedersleben: Moderne Softwarearchitektur]

12 Beispiel Borrowing 12

13 Details Borrowing Pre condition Post condition 13

14 Documenting the implementation Use descriptive class / method / variable names no need for elaborate implementation documentation if (tmp == 0) {... } What the hell is tmp? if (size == 0) {... } All right, size of the list If algorithmic logic is not obvious add inline comments: if (size == 0) { // list empty... } else { // list not empty... } 14

15 Agenda 1. Documenting with JavaDoc 2. Quick check 15

16 Quick check Documenting 1. How to document the client s view of classes and methods? 2. How to document the implementation view?