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.
- 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.
- 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.
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:
- A Class 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 management 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 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
- 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
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 |