DOC

Documentation of Java Programs

By Ethel Roberts,2014-04-24 12:57
10 views 0
Documentation of Java Programs

Software Development

    Documentation of Java ‘Programs’

    A Java program designed to run on the java virtual machine consists of an application class and (zero or more) classes developed by the designer of the program. It also uses (‘imports’) library classes (eg

    java.io.*) and other re-usable classes (eg classes from Java Gently). The application class in a program

    is the one which contains the

    public static void main(String [] args)

    method. The other classes usually contain private data structures and a number of public and private

    methods.

    The documentation consists of a number of sections for each class: description, data and methods.

    What follows is a description of how to document java programs and an edited example. The parts

    surrounded by chevrons <...> and the chevrons should be replaced by appropriate text. The examples

    are drawn from the WaitingRoom and other classes [Bishop 3rd Edn, Ex 15.3, pp 621-623]

    Documentation for an Application Class

    Application-Requirements

    Application Class:

    Designer:

    Date:

    Requirements:

    

    and the outputs to the program (see Data Items) are related. It is useful to give sketches of the

    appearance of the program in operation. This section could also refer to other documents e.g. the Phase

    1 Requirements Document and the original user brief (e.g. to describe the context). You should avoid

    describing the classes used here as this is really part of the design.>

    Environment:

    Virtual Machines: < list of the Java Virtual Machines on which the program is designed to run >

    Class libraries Used:

    Classes Used:

    Input/Output items:

    Item Name Input/Output Item Type or Class Item Range Comment of values item, make it O for name> the item can take, if for clarification, appropriate to the output, I/O appropriate> where necessary> application> for input

    and output>

     chairs O Queue n/a chairs in the waiting

    room (7 chairs

    altogether)

     Page 1 of 7 RDK, CH 24/04/10

Software Development

    Application-Design

    Application Class:

    Designer:

    Date:

    Functional Decomposition:

    

    designs of any ancillary methods. The functional decomposition can be hand drawn.

    Example

    WaitingRoom.main

    header messagerun surgery

    29 times

    arrive and*

    see doctor

    display timedisplayconsult waiting

    and choicechairsand arriveroom full

    (page x)

    consultarrivechoice = 1 or 2choice = 2, 4 or 6

    see Ooccupy O

    doctorchairchairs not empty

    leave O

    chair

     This diagram indicates that display is an ancillary method (a method used in the application class to

    simplify the programming in the main method) and shows that display’s design can be found on page x

    of the documentation>

    Local Variables:

    Identifier Type or Class Comment

    declarations at the beginning of

    the main method>

     patient Item choice int randomly generated value (1 - 6)

    used to control arrival and

    consultation of patients

     Page 2 of 7 RDK, CH 24/04/10

Software Development

    Application-Source

    Application Class:

    Designer:

    Date:

    Code Fragment:

    

    Example

    class WaitingRoom {

     /* Simulation the Waiting Room by J M Bishop Jan 1997

     * --------------------------- Java 1.1

     * Shows a queue growing and shrinking in response to

     * random events.

     * Illustrates queues and queue iterators.

     */

     public static void main (String args []) throws QueueException {

     Queue chairs = new Queue (7);

     item patient;

     int choice;

     System.out.println("*** Doctor's Waitintg Room Simulation ***");

     System.out.println("There are 7 chairs");

     System.out.println("Arrivals on 2,4,6; patients seen on 1,2");

     System.out.println();

     System.out.println("Time\tChoice\tPatient numbers");

     for (int i = 2; i<30; i++) {

     choice = (int) (Math.random()*6+1);

     System.out.print(i+"\t"+choice+"\t");

     display(chairs);

     try {

     if (choice == 1 || choice == 2)

     if (!chairs.empty())

     patient = (item) chairs.remove();

     if (choice == 2 || choice == 4 || choice == 6)

     chairs.add(new item(i));

     }

     catch (QueueException e) {

     System.out.println("\t\t\tWaiting room "+e.getMessage());

     }

     }

     }

    >

    Ancillary Methods Used:

    Example

    static void display(Queue q)

    >

     Page 3 of 7 RDK, CH 24/04/10

Software Development

    Application-Ancillary Methods

    For each ancillary method, the following should be provided:

    Application Class:

    Designer:

    Date:

    Method:

    Specification:

    

    Example

    Displays the contents of a queue on the VDU

    >

    Modifier:

    Source section of the document>

    Return Type:

    Parameters:

    Identifier Type or Class Comment

    

    Methods in Application-Methods in Application-Source> Source>

     q Queue> Functional Decomposition:

    

    Example

    WaitingRoom.display

    print queueprint line

    empty queuenon-empty queue

    print mpty? Oprint all elements O

    for all elements

    print element *

     >

    Local Data:

    Identifier Type or Class Comment

    

    

    Code Fragment:

    

    Example

    static void display (Queue q) {

     if (q.empty()) System.out.print("Empty"); else

     for (q.reset(); !q.eol(); q.succ())

     System.out.print(((item)q.current()).data+" ");

     System.out.println();

     }

     Page 4 of 7 RDK, CH 24/04/10

Software Development

    }

    >

     Page 5 of 7 RDK, CH 24/04/10

Software Development

    Documentation for other (non-application) Classes.

    These are the other classes used in the program. For each one, the following should be provided

    Class-Summary

    Class:

    Designer:

    Date:

    Purpose:

    

    Example (from Queue class)

    To provide for the instantiation of a queue of arbitrary objects with the following behaviour:

    elements are added to the queue at one end (the back) and removed from the queue at the other (the

    front); elements leave the queue in the same order as they arrive; this might be referred to as a first-in-

    first-out (FIFO) structure.>

Constraints:

    

    Example

    The queue is bounded - maximum number of elements 100>

Attributes:

Class attributes:

    Identifier Modifier Type or Class Comment

     ss >

    clarification> maxQueue private int Max Queue capacity

Instance attributes:

    Identifier Modifier Type or Class Comment - put the private ones last in this clarification> section>

     size private int queue capacity front private int indicator of the front of

    the queue back private int indicator of the back of

    the queue>

Methods:

    < A list of the class methods, constructor/s first. This should give the method signatures and a mini-

    specification>

    Example

    void add(Object x)

     adds the object x to the back of the queue as long as the queue is not full.

    Object remove()

     removes the object from the front of the queue and returns it as long as the queue is not

     empty>

     Page 6 of 7 RDK, CH 24/04/10

Software Development

    Class-Methods

    This section gives full details of the class methods. It has the same structure as the Application-

    Ancillary Methods section in the Application Classes part of the document. That is:

    For each method, the following should be provided:

Class:

    Designer:

    Date:

    Method:

    Specification:

    

    Modifier:

    Return Type:

    Parameters:

    Identifier Type or Class Comment

    

    Functional Decomposition:

    

    Local Data:

    Identifier Type or Class Comment

    

    Code Fragment:

    

     Page 7 of 7 RDK, CH 24/04/10

Report this document

For any questions or suggestions please email
cust-service@docsford.com