Design Document Format

High Level Design Document Format

Cover Page

Team Name, Logo (optional), Deliverable name (e.g. "Web Calendar Design Document"), Date, Course-Section.

Credits Page

Clearly describes each group member's contribution in producing the deliverable.

Design Overview

This is the first place other developers/maintainers will look to learn how your project works. It must provide a comprehensive outline of the entire design. The design lead is responsible for writing the overview. Write this section as HTML and place it in the javadoc overview file.

Identifying info: project name, team name, authors, version, date, etc.
Design Overview. This crucial section provides an overall view of your design. Use your best technical writing to communicate to other designers the framework of your design solution. It must clarify the essence of your design to someone who is not familiar with it. Try to limit this to one page.
Design Issues. There are many tradeoffs in design, a few of which we discussed in class. Describe the key design issues raised in your project, what decisions (or tradefoffs) you made, and your rationale. (You can think of this section as being the background that lead to your Overview above). This section may be 3 pages or longer. Examples of Design Issues
Tools: Compilers and other development tools used, and their version numbers.
Libraries: Indicate what pre-existing libraries are used in your design, why you selected them, any licensing restrictions that may apply.
External References: Indicate where associated project documents can be found: specification document, prototype, structure chart diagram, design patterns, coding standards, etc. If these references are in digital form provide the file name or URL. MAKE SURE THESE ARE ACCURATE when the finished deliverable is submitted.

Class Diagram or Structure Chart

This diagram is the core of your design. Think of it as the blueprint of your software design. This diagram shows the relationship among all the classes in your design. You need not show the classes that create and operate the GUI. It's recommended that you use a design tool such as Rational Rose to facilitate ease of modification (as this chart changes a lot during the design phase). Quality hand illustration is an acceptable alternative. The chart may be quite large. If it spans multiple pages be sure the page ordering or hierarchy is clearly indicated through some page numbering scheme or connector labels. You may create your finished chart on a single large piece of poster board if you desire. (One advantage of this is that it can be hung on the wall of your team meeting space.) Alternatively, place an image of your class diagram on your team web page.

Note: If you are reusing code don't draw the entire structure of the reused code.
Note: If significant portions of your solution are functions (i.e., complex methods) rather than classes consider showing their decomposition with a structure chart.

Class Skeletons or Module Headers

You must implement and compile (not execute) the class definition for each class in your class diagram. (Don't forget to count compile defects - see QA plan). The purpose and interface for the class is documented as Javadoc comments and must adhere to Javadoc style. The Javadocs can be placed on your team web page.

Each class in your system is to be assigned to an individual author who designs the class and writes the class definition. Each team member is responsible for at least one prominent class in your system.

A class definition consists of:

A Class Header

Identifying info: Class name, @author, @version, date, etc.
Descriptive Header

Method headers

Method (Operation) name - must correspond exactly with the name shown on the class diagram.
Purpose - Describe the purpose of this operation. Must be a concise, clear English sentence using terms from the problem domain.
Parameters and return types - name, type, and description.
Exceptions thrown.
(Design By Contract teams) Pre- and Post- conditions (except for getter/setter methods). Recommended: use custom tags
(Error-Checking teams) Document all error handling.

Notes:

Read and adhere to the conventions for Javadoc style.
Refer to this example of javadoc for a class definition and the source which produced it.
Consider grouping your classes using the Java packages framework. One common approach is to separate View classes (e.g. GUI) from Model classes.
If you are reusing code, don't include the headers of the reused code.
Your ADT's must handle their own persistence. That is, you can't use a DBMS or file system provided by the target system. Consult the instructor if you have questions or want to negotiate this constraint.

Interaction Diagrams (as appropriate)

Also known as sequence diagrams or event trace diagrams. They provide specific details about the order in which events occur and how the classes interact. They show the sequence in which objects pass messages to each other. Use some standard diagramming notation such as UML. Rational Rose or similar tool recommended. How do you decide appropriateness? Use your judgement to determine which Use Cases are complex enough that you need to clarify the interations. As a guideline, an interaction diagram is probably appropriate if the Use Case has more than two objects involved, or has more than four steps.

Data Structures

Internal

Document how you have decided to implement your data abstractions. Provide a javadoc comment for each composite data structure in your solution. (I.E., array, vector, etc). This implementation should be private, so you will need to used the -private flag on the javadoc command. Be sure for each major data structure there is a rationale provided in "Design Issues" which explains your implementation choice.
Example:

/** The cipher key is an array of 26 characters, 
 *  one to correspond to each letter of the alphabet. 
 */
private char[] CipherKey;

External

If your design includes external data files, show the exact format/contents of each file using javadoc in the appropriate class in your design.

Appendix

FTR Review Summary report
Compilation Listings showing a successful compile of all modules. If you are using JDK, use the -verbose flag on javac and include a screen capture of the output. Also include the output from the javadoc command.
QA Checklist, (with items checked off), signed by your QA person. You must provide an explanation for any items not checked off. If an item is missing or obviously unsatisfactory that has been checked off, the entire document will be returned for correction and a late penalty will accrue.

Submitting your high level design

Submit printouts of all the items above in an inexpensive 3-ring binder. If your design diagram is extremely large you may submit your finished chart on a single large piece of poster board.
Order the javadocs in alphabetical order.
Follow the writing requirement guidelines for all other printed output.

Document History

Date Author Description

11/21/03
J. Dalbey
Added submission guidelines.

11/17/01 J. Dalbey Minor edits and clarifications.
Added an example class definition in Javadoc.

5/15/01 J. Dalbey Removed PSP forms

4/28/01 J. Dalbey Revised for Spring 2001

11/25/00 J. Dalbey Moved Software Architecture to Design Issues and added examples of Design Issues.
Added an example of an ADT description.

11/20/00 J. Dalbey Added Defect logs to appendix

Date	Author	Description
11/21/03	J. Dalbey	Added submission guidelines.
11/17/01	J. Dalbey	Minor edits and clarifications. Added an example class definition in Javadoc.
5/15/01	J. Dalbey	Removed PSP forms
4/28/01	J. Dalbey	Revised for Spring 2001
11/25/00	J. Dalbey	Moved Software Architecture to Design Issues and added examples of Design Issues. Added an example of an ADT description.
11/20/00	J. Dalbey	Added Defect logs to appendix