Detailed Design Document Format
There is no separate detailed design document.
The detailed design consists of algorithms (pseudocode)
which are inserted as comments in the class definition files. That is,
the class files you created during high level design are augmented with
the algorithm pseudocode. In many cases your algorithm can be derived
from the Interaction Diagrams created in your high level design.
You do not need to provide algorithms for code that was
generated by a GUI builder.
You DO need to provide algorithms for any functionality which you add
to the generated code.
You do not need to provide algorithms for get/set methods (or other
similarly trivial methods).
(Spring 2001) You DO need to keep PSP forms for your detailed design
(Spring 2003) You only need to provide algorithms for the modules you
will be implementing
this quarter (refer to your Staged Delivery Plan and Implementation
In the example below (for the Java language), the bold text was added
the source file during detailed design.
The advantage of writing each line of pseudocode as an independent
comment is that it makes it simple during implementation to insert
source code in between the comment lines.
* Reads the customer numbers and PINs
from the customers.txt file.
* Creates a new customer for each line
of the file and calls addCustomer
* to add them to the bank.
* @param filename the name of the customer
// Version History
Joe Student added algorithm pseudocode
public void readCustomers(String filename) throws
// OPEN the customer
file for reading
// READ a line from
// WHILE the line
is not null LOOP
// EXTRACT the customer number and PIN from the line
// CONSTRUCT a new customer with the # and PIN
// CALL addCustomer with the new customer
// READ a line from the file
// END WHILE
// CLOSE the file
Note: If a single person authors the entire class, you don't need to
include a version history comment for every method, just one is needed
for the class.
Submitting your detailed design
The pseudocode is comments in your source code.
Run the javadoc command with the "-linksource" command flag.
The resulting html will have hyperlinks from the method names
to the actual source code.
Post this javadoc output on your team web site.
- Right-click on the project and choose "Properties."
- In the Project Properties dialog,
click on "Documenting" in the Categories panel on the left.
- Enter "-linksource" in the text field for "Additional Javadoc Options".
- Click OK.
- Right-click on the project and choose "Generate Javadocs."
Quality Assurance Guidelines
[ ] Design document format guidelines are followed?
[ ] All narrative text meets the class writing standards?
- [ ] Is there an algorithm corresponding to each method in the
(or module in the structure chart)?
- [ ] Are the algorithms correct? Does the internal logic achieve
- [ ] Does the algorithm avoid redundant or duplicate code? Code
similar to code in another place must be combined so the code is
only once, in a procedure or function. Use parameters to accomodate
in similar code segments.
- [ ] Does each algorithm perform just a single task that can be
coded in less
30 lines (approximately)?
- [ ] Is the algorithm coded as comments in the module body?
- [ ] Is the algorithm described WITHOUT any syntax details? Could
implemented in ANY programming language. Does it use a language
notation such as Pseudocode, Nassi-Shneiderman Charts, PDL (program
language)? Use this pseudocode
standard unless you have another approved by the instructor.
- [ ] Does the low level design describe enough detail that it can
directly into code? (The coder should not have to create any
- [ ] Does the algorithm follow principles of
structured programming? (pdf)
- One entry - one exit control structures. Enter at the top,
exit at the
Do not use EXIT or GOTO.
- Avoid loops which exit (or "break") from the
- Don't have empty (or "null") else clauses.
- Multiple return
from a function should be avoided.
Functions must not have side effects.
- [ ] Are counting and conditional loops used properly?
- [ ] Are boolean functions invoked properly? (JD's pet peeve:
Don't use WHILE
Is_More_Data() == TRUE, just WHILE Is_More_Data()).
- [ ] Are boolean return values computed properly?
IF (booleanExpression) THEN
should instead be written as
- [ ] Do the algorithms avoid brute force
- [ ] Do the algorithms capitalize on third party libraries where
appropriate (e.g, sorting, command line parsing)?
- [ ] In the case where the implementation language is known before
design, do the algorithms take advantage of features of the
language (e.g. serializable)?
- [ ] Is each method a "primitive?" I.e., it can't be constructed
sequence of other operations within the class.
- [ ] Is method complexity (e.g., McCabe's cyclomatic
complexity) as small as possible (less than 5 is good)?
- [ ] Is the representation for each ADT included (and documented)?
if you have a EmployeeList ADT, the detailed design should show your
of representation: array or list or ...?
- [ ] Does every variable declaration have an explanatory sidebar
(or javadoc comment)?
- [ ] Has a version history field been added to the original design
- [ ] (Optional). Has the algorithm been desk checked for
a pencil and paper execution trace?
- [ ] (Optional). Has each functional requirement in the
a design walkthrough?
- [ ] (Negotiate with instructor). Are program stubs coded which
call subordinate modules? In other words, have you produced a
program skeleton? Is a printout of the successful compilation included?
Attach extra pages as needed to explain any unchecked
||Add function side-effect prohibition
|Minor revisions and additions for Fall 2003
||Added item for computing return values
||Revised for Fall 2001
||Revised for Spring 2001