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 directly from the Interaction Diagrams created in your high level design.

You do not need to provide algorithms for code that was automatically 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 work.
(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 Plan).



In the example below (for the Java language), the bold text was added to 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 actual 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 file.
    //  Version History
    //       2/23/99 Joe Student added algorithm pseudocode

  public void readCustomers(String filename) throws IOException
        // OPEN the customer file for reading
        // READ a line from the file
        // 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.
NetBeans tip:
  1. Right-click on the project and choose "Properties."
  2. In the Project Properties dialog, click on "Documenting" in the Categories panel on the left.
  3. Enter "-linksource" in the text field for "Additional Javadoc Options".
  4. Click OK.
  5. Right-click on the project and choose "Generate Javadocs."

Quality Assurance Guidelines

  1. [ ] Is there an algorithm corresponding to each method in the class diagram (or module in the structure chart)?
  2. [ ] Are the algorithms correct? Does the internal logic achieve the desired result?
  3. [ ] Does the algorithm avoid redundant or duplicate code? Code that is similar to code in another place must be combined so the code is written only once, in a procedure or function. Use parameters to accomodate differences in similar code segments.
  4. [ ] Does each algorithm perform just a single task that can be coded in less than 30 lines (approximately)?
  5. [ ] Is the algorithm coded as comments in the module body?
  6. [ ] Is the algorithm described WITHOUT any syntax details? Could it be implemented in ANY programming language. Does it use a language independent notation such as Pseudocode, Nassi-Shneiderman Charts, PDL (program description language)? Use this pseudocode standard unless you have another approved by the instructor.
  7. [ ] Does the low level design describe enough detail that it can be translated directly into code? (The coder should not have to create any algorithms).
  8. [ ] Does the algorithm follow principles of structured programming? (pdf)
  9. [ ] Are counting and conditional loops used properly?
  10. [ ] Are boolean functions invoked properly? (JD's pet peeve: Don't use WHILE Is_More_Data() == TRUE, just WHILE Is_More_Data()).
  11. [ ] Are boolean return values computed properly?
  12. IF (booleanExpression) THEN
             RETURN true
             RETURN false
    END IF
    should instead be written as
         RETURN booleanExpression;
  13. [ ] Do the algorithms avoid brute force solutions?
  14. [ ] Do the algorithms capitalize on third party libraries where appropriate (e.g, sorting, command line parsing)?
  15. [ ] In the case where the implementation language is known before design, do the algorithms take advantage of features of the language (e.g. serializable)?
  16. [ ] Is each method a "primitive?" I.e., it can't be constructed from a sequence of other operations within the class.
  17. [ ] Is method complexity (e.g., McCabe's cyclomatic complexity) as small as possible (less than 5 is good)?
  18. [ ] Is the representation for each ADT included (and documented)? For example, if you have a EmployeeList ADT, the detailed design should show your choice of representation: array or list or ...?
  19. [ ] Does every variable declaration have an explanatory sidebar comment (or javadoc comment)?
  20. [ ] Has a version history field been added to the original design module header?
  21. [ ] (Optional). Has the algorithm been desk checked for correctness by a pencil and paper execution trace?
  22. [ ] (Optional). Has each functional requirement in the specification undergone a design walkthrough?
  23. [ ] (Negotiate with instructor). Are program stubs coded which actually call subordinate modules? In other words, have you produced a compilable program skeleton? Is a printout of the successful compilation included?

Attach extra pages as needed to explain any unchecked items.

Document History
Date  Author Changes
5/31/09 JD Add function side-effect prohibition
Minor revisions and additions for Fall 2003
11/24/02  JD Added item for computing return values
11/16  JD Revised for Fall 2001
4/28  JD Revised for Spring 2001