Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
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