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. Follow these guidelines.

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.
  1. Identifying info: project name, team name, authors, version, date, etc.
  2. 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. 
  3. Tools: Compilers and other development tools used, and their version numbers.
  4. Libraries: Indicate what pre-existing libraries are used in your design, why you selected them, any licensing restrictions that may apply.
  5. 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.

UML Deployment Diagram (optional)

If your system has more components than just a single desktop application, you should create a UML Deployment diagram to show the relationships between all the subsystems.

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 Violet or Argo UML 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 (aka "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:

  1. A Class Header
  2. Method headers
Notes:

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 use 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.

Design Rationale

A Design Rationale is a framework of the reasons behind decisions made when designing a system. (Wikipedia article). 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.  Use the same format as for Analysis Rationale (SRS 6.2). Examples of Design Issues

Appendix

  1. FTR Review Summary report
  2. 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.
  3. 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

All items EXCEPT the Appendices may be posted electronically on the team wiki. In this case you don't need a cover page. The Appendices must be printed and submitted at the start of lab on the due date.

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