Download Documentation of Java `Programs`

Software Development
Documentation of Java Programs
These notes are to help with the ‘formal documentation’ part of your phase 2 deliverables. These notes
are in 4 sections:
1.
2.
3.
4.
Introduction, making it clear how the programme documentation works overall.
A template for full documentation of an Application Class.
A template for full documentation of other classes.
Summary only documentation for classes.
1. Introduction.
A Java program designed to run from the Java Virtual Machine consists of an Application Class (which
contains a main method - public static void main(String [] args)) and other
classes developed by the designer of the program. Usually, it also uses (‘imports’) library classes (eg
java.io.*) and other re-usable classes (eg the Display and Stream classes from Java Gently).
The documentation is done class by class, with the Application Class first. It consists of a number of
sections for each class: description, attributes and methods. In the rest of these notes there are
templates showing how to document java classes and some examples. The parts surrounded by
chevrons <...> are not part of the examples - they are just notes to make things clearer for you. The
main examples are drawn from the WaitingRoom program and its related classes [Bishop 3rd Edn, Ex
15.3, pp 621-623]
The Application Class may or may not be the one that does the real work of the program. For example,
in a small harness program written to test a class you have written, the main method of the Application
Class will often be where the tests are actually run (creating an object of the class being tested, running
its methods). In a larger program, the main method of the application class may serve simply to create
an object (or maybe a few objects) whose methods then take over the main work to be done (this is
likely to be the case in your assignment). What is important is that the formal documentation begins
with an architectural overview of how the various classes deliver the functionality of the program. The
individual classes, their attributes and methods, can then be described in more detail. So your program
documentation should be in three parts:
A
An overview of the architecture. This can be based on UML diagrams for the classes, along
with a clear description, in English, about how it all works together. For instance, it should be
clear from this section which part or parts of the program interacts with the external data flows
which you identified on the Context Diagram in your Phase 1 report, particularly the interfaces
with the user.
B
Documentation for the Application Class. For the final version of your program, this will
probably be very short. But all applications are run from the java command line, and this makes
application classes a bit different from others and essential to document.
C
Documentation for other classes. This will be the largest part of the documentation. This
documentation could be in full, or in summary form, with only 'Black Box' descriptions of the
methods – you will be told which in the list of deliverables for phase 2.
Java Documentation 05-06
Page 1 of 9
RDK
Software Development
2. Documenting the Application class
< Each new section of the documentation should be start on a new page and begin with a header giving
the class name, the designers name and date, as in the example below. If the section runs over to a new
page you don't need to repeat the header just because it's a new page >
Application Class: WaitingRoom
Designer: J Bishop
Date: 14 Jan 2000
Purpose:
<A description of what the application class, via its main method, actually does. Any input from the
command line will need to be specified . An example from Java Gently is given below >.
This application program implements the queue demonstration given in Java Gently page 621. The
function of the demonstration is entirely implemented by the application's main method, described on
page xxx of this documentation.
< The fact that this JG program does all the work in its main method is not so good! As we discussed in
lectures >
Environment: < Only an Application Class will have this section, since it is only the Application
Class's main method which gets called from the JVM. >
Virtual Machines:
Class libraries Used:
Classes Used:
< Give a list of the Java Virtual Machines on which the program is designed
to run, usually this will be the default JVM of Windows XP etc >
<Give a of the Java libraries needed to support the program (i.e. those it
imports). You might also say here what a recommended Classpath might
be>
<list of the other classes used in the program, apart from the Application
Class, along with their page numbers in the documentation or references to
other documentation. >
Attributes: < It is unusual for the Application Class to have any attributes - either the programme's
work is done by the main method, in which case the necessary variables and objects will be declared in
the main method, or the program's work will be done by methods in an object or objects created by the
main method, in which case all the attributes will belong to these objects. See section 3 of these notes
'Documenting a Non-Application Class, for how to set out the attributes section for a class >
Methods < There will be a documentation section for every method of the class, with the constructor
method/s first, if any. The documentation for each method will start on a new page and have a header,
as in the example below. For each method, there are the following sections:
Specification
Return Type
External I/O, if any
Parameters
Functional Decomposition, unless trivial
Source Code
Start each method on a new page, since you might want to copy or distribute just the documentation for
a single method >
Java Documentation 05-06
Page 2 of 9
RDK
Software Development
Class: method: WaitingRoom: main <the class name containing the method and the method name>
Designer: Judy Bishop
Date: <Jan 12 2000>
Specification: < A description of what the method does - this should be complete and clear, but could
refer for extra detail to other parts of the documentation, e.g. to Phase 1, to an appendix, or to special
diagram. The example below is for the main method of the Java Gently program to illustrate the use of
the Queue class >
This method will simulate a doctor's waiting room. There are 7 chairs in the room. New arrivals and
patients seeing the doctor are simulated by the values of a randomly generated number. The state of the
queue is continuously displayed with an indication of when the queue is full. When the queue is full
arrivals are ignored (as if they have decided to go away and, perhaps return later). The method will
produce the following display for 20 simulated arrivals:
< Notice that diagrams such as the one below can be very useful in describing what a method does - you
can show a sample of how a menu would look, for example >
Arrivals on 2,4,6; patients seen on 1,2
Time
Choice Patient numbers
2
1
Empty
3
1
Empty
4
4
Empty
5
2
4
6
3
5
7
4
5
8
4
5 7
9
6
5 7 8
10
5
5 7 8 9
11
6
5 7 8 9
12
3
5 7 8 9 11
13
3
5 7 8 9 11
14
4
5 7 8 9 11
15
1
5 7 8 9 11 14
16
1
7 8 9 11 14
17
2
8 9 11 14
18
1
9 11 14 17
19
4
11 14 17
Return type:
void
< Every method has a return type, void or some actual type or class - so a section for this is always
needed >
Parameters: <most methods have parameters (unless the parentheses are empty, for example as in
toString() ). Parameters are the main way in which methods communicate with each other and the rest
of the world (remember our discussions about encapsulation), so it is very important to have a clear list
of parameters, and what they are for - so never omit the comments part below.>
Identifier
Type or Class of the parameter
Comment < saying what the
parameter is for>
<Example below >
args [ ]
array of String
not used, since this main method
doesn't use command line input
External I/O: <this section is only needed if the method does external I/O - otherwise just enter
"none" for this section >
Item Name
Input/Output Item Type or Class
Item Range
Comment
< name of the data < I for input, < type or class of
< the range of
<always include
item, make it
O for
the item >
values the item can
comments for
Java Documentation 05-06
Page 3 of 9
RDK
Software Development
appropriate to the
application >
<Example below>
chairs
output, I/O
for input
and output >
O
Queue class < ie
chairs is an object
of the Queue class >
take, if appropriate
>
clarification, even if
the item seems
obvious>
N/A
chairs in the waiting
room (7 chairs
altogether)
Functional Decomposition:
< Functional Decomposition (FD) of the method. This should include page references to the
documentation of any ancilliary methods it calls (as in display chairs in the example below). The FD
can be hand drawn, and FDs can be omitted if the method concerned is trivial. >
Example
WaitingRoom.main
header message
run surgery
29 times
arrive and*
see doctor
display time
and choice
display
chairs
consult
and arrive
waiting
room full
(page x)
consult
choice = 1 or 2
see O
doctor
arrive
choice = 2, 4 or 6
occupy O
chair
chairs not empty
leave O
chair
< The 'page x' reference in this diagram indicates that 'display chairs' is an ancillary method (a method
used to simplify the programming in the main method) and shows that 'display chairs's design can be
found on page x of the documentation>
Java Documentation 05-06
Page 4 of 9
RDK
Software Development
Local Declarations: <i.e any local things that are declared in the method>
Identifier
Type or Class
Comment
<identifier as it appears in the
< type or class of the declaration < comment for clarification >
declarations at the beginning of
>
the main method>
< Example below from the JG
waiting room program >
patient
Item class
Patients are represented as
objects of the Item class
choice
int
randomly generated value (1 - 6)
used to simulate the arrival and
consultation of patients
Source Code
< This is sometimes called a 'Code Fragment', since it is not complete, in the sense that it could be
compiled or run on its own. It contains the data declarations and the Java code derived from the
previous Functional Decomposition section. It should follow the South Bank 'house standards' for
indentation etc. This means that if it is typed, it should be in the courier font where each character
takes up the same horizontal space >
Example
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<20; i++) { // loop for 20 cases, as in spec
choice = (int) (Math.random()*6+1); // note the casting
System.out.print(i+"\t"+choice+"\t");
display(chairs);
try {
if (choice == 1 || choice == 2)
if (!chairs.empty()) // uses the Queue class 'empty' method
patient = (item) chairs.remove();
if (choice == 2 || choice == 4 || choice == 6)
chairs.add(new item(i));
} // of try
catch (QueueException e) {
System.out.println("\t\t\tWaiting room "+e.getMessage());
} // of catch
} // of for loop
} // of main
Java Documentation 05-06
Page 5 of 9
RDK
Software Development
3. Documenting a Non-Application Class
< This follows more or less the same pattern as for the Application Class, except there is no section for
'Environment', whereas there will be class attributes to describe. Remember that these Non Application classes will form the bulk of your program. Again, the example is from the JG waiting
Room example. >
Class: Queue
Designer: Judy Bishop
Date: Jan 1997
Purpose:
< This is the description of what the class is for >
The Queue class provides 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 is normally referred to as a firstin-first-out (FIFO) queue.
Attributes: < sometimes called fields or data - we are calling them attributes >
Class attributes: < These come first. i.e. those which are static and so belong to the class, not to any
objects. Some classes do have attributes that belong to the class, rather than to objects created from the
class. Your program probably won't contain any of these >
Identifier
Modifier <public,
Type or Class
Comment
private, etc>
<Example>
maxQueue
private
int
Max Queue capacity,
e.g. 100
Instance attributes: <i.e. those possessed by every object (instance) of the class >
Identifier
Modifier
Type or Class
Comment
< example below >
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
live
private
int
number of used spaces
in the queue
now
private
int
position for displaying
the queue
Q
private
array of Object
can contain up to
maxQueue objects
Java Documentation 05-06
Page 6 of 9
RDK
Software Development
Methods
Class: Queue:Queue < same name shows that this is a constructor method >
Designer: J Bishop
Date: Jan 1997
Specification:
Constructs a queue of size m. If m > 100 the size is set to 100. After the operation:
size = m or maxQueue if m > maxQueue and
front = 0
back = -1
live = 0
now = 0
Return Type: Queue object
Parameters:
Identifier
m
Type or Class
int
Comment
Required size or length of the
queue
Functional Decomposition:
Queue
Set size
initialise
size < maxQueue
o
size = m
o
size =
maxQueue
Local Variables: None
Code Fragment:
Queue(int m) { // Constructor method for Queue class
// creates a Fifo Queue of m elements
if (m <= maxQueue) size = m;
else size = maxQueue;
front = 0;
back = -1;
live = 0;
reset();
} // of Queue constructor
Java Documentation 05-06
Page 7 of 9
RDK
Software Development
Class: Queue:add
Designer: J Bishop
Date: Jan 1997
Specification:
Adds an object to the back of the queue. If the queue is full it throws a QueueException ("Full").
Before the call to the add method:
Either
The queue is not full (i.e. a call to the full()method would return false) In this case,
'back' is incremented (mod maxQueue) and Q[back] = x.
Or
The queue is full (i.e. a call to the full()method would return true) In this case a
QueueException("Full") is thrown and all data about the queue object remains unchanged
Return Type: void
Parameters:
Identifier
x
Type or Class
Object
Comment
element to add to the queue
Functional Decomposition: < This is an example where the FD could easily have been omitted, since
all is clear from the code fragment >
add
live < size
o
add to Q
o
throw “Full”
Local Variables: None
Code Fragment:
void add(Object x) { // adds an object x to the queue, if not full
if (live < size) {
back = (back + 1) % maxQueue; // note modular arithmetic
Q[back] = x;
live ++;
} // of if
else
throw new QueueException("Full");
} // of add
Java Documentation 05-06
Page 8 of 9
RDK
Software Development
4. Summary Documentation for Classes
There may be classes which have been re-used (or for other reasons have full documentation
elsewhere). In this case, we need enough documentation to understand the use of the class and a
reference about where to find more details if we need it. In this case, we need the summary
documentation below, for each class. Document such classes as below, starting with a header.
This documentation is essentially the same as the full documentation described in 3. above, except that
methods are just described in 'Black Box' terms.
Class: Queue
Designer: Judy Bishop
Date: Jan 1997
Purpose:
< This is the description of what the class is for >
The Queue class provides 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 is normally referred to as a firstin-first-out (FIFO) queue.
Attributes:
Class attributes: <i.e. those which are static>
Identifier
Modifier <public,
private, etc>
<Example>
maxQueue
private
Type or Class
Comment
int
Max Queue capacity,
eg 100
Instance attributes: <i.e. those possessed by every object (instance) of the class >
Identifier
Modifier
Type or Class
Comment
<identifier - put the
<public, private, etc>
<type or class >
<comment for
private ones last in this
clarification>
section>
<Example >
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 'Black Box' summary of the class methods, constructor/s first. Often, your program may only use
some of the methods of a class - in this case give a proper Black Box description of the methods that
your program does use and simply note that other methods of the class exist (without necessarily giving
a list), along with a reference of where to find out about them. For each method which is in your
summary, you should give the method heading followed by a mini-specification. If there are
parameters, the mini spec should say how they are used and if the method does any external I/O, the
mini spec should also say what this is. >
Examples
void add(Object x)
Adds the object x to the back of the queue as long as the queue is
not full (generates a QueueException if this is the case).
Object remove()
Removes the object from the front of the queue and returns it as
long as the queue is not empty>
Java Documentation 05-06
Page 9 of 9
RDK