2D1363, Mjukvarukonstruktion, 8 poäng

Aktuell kursomgång: period 2-4 06/07

Kursledare: Rand Waltzman
Datorpostadress(er): rand@nada.kth.se

 

Design Document Template

This page contains a detailed description of the DD.  See Design Document Guidelines for some general guidance.

Professor Russell Bjork of Gordon College has been gracious enough to make publicly available a fairly complete example of object-oriented analysis, design, and programming applied to a moderate size problem: the simulation of an Automated Teller Machine.  You will find detailed descriptions and excellent examples of most (but not all) of the essential requirements of your design document in his documentation that spans a number of web pages.  Before you begin your work, I strongly recommend that you carefully study his Introduction section.  Specific references to his documentation are provided in the document template below.

Also, I suggest you study through the following checklist of questions that you should keep in mind while you work:

Architecture Considerations:

  • Is the overall program organization clear, including a good architectural overview and justification?
  • Are modules well defined including their functionality and interfaces to other modules?
  • Are all the functions that are listed in the requirements covered sensibly, neither by too many nor too few modules?
  • Are all major data structures described and justified?
  • Are major data structures hidden with access functions?
  • Is the database (if any) organization and content specified?
  • Are all key algorithms described and justified?
  • Are all major objects described and justified?
  • Is the user interface modularized so that changes in it won't affect the rest of the program?
  • Is a strategy for handling user input described?
  • Are key aspects of the user interface defined?
  • Are memory use estimates and a strategy for memory management described and justified?
  • Is a strategy for handling I/O described and justified?
  • Is a coherent error-handling strategy included?
  • Are necessary buy vs. build decisions included?
  • Is the architecture designed to accommodate likely changes?
  • Is any part over- or under-architected?
  • Are the major system goals clearly stated?
  • Does the complete architecture hang together conceptually?
  • Is the top-level design independent of the machine and language that will be used to implement it?
  • Are motivations given for all major decisions?
  • Are you, as a programmer who will implement the system, comfortable with the architecture?

High-level Design Considerations

  • Does the design adequately address issues that were identified and deferred at the requirements level?
  • Are you satisfied with the way the program has been decomposed into modules or objects?
  • Are you satisfied with the way that modules have been decomposed into routines?
  • Are subprogram boundaries well defined?
  • Are subprograms designed for minimal interaction with each other?
  • Does the design make sense both from the top down and the bottom up?
  • Does the design differentiate between the problem-domain component, the user-interface component, the task-management component and the data-management component?
  • Is the design intellectually manageable?
  • Does the design have low complexity?
  • Will the program be easy to maintain?
  • Does the design hold connections among subprograms to a minimum?
  • Does the design account for future extensions to the program?
  • Are subprograms designed so that you can use them in other systems?
  • Will the design be easy to port to another environment?
  • Is the design lean? Are all of its parts strictly necessary?
  • Does the design use standard techniques and avoid exotic, hard-to-understand elements?

Your design document must have the following sections.  Any additional material that you might find helpful is welcome.

1. Introduction

Provide an overview of the entire document:

  • Describe the purpose of this document
  • Describe the scope of this document
  • Describe this document's intended audience
  • Identify the system/product using any applicable names and/or version numbers.
  • Provide references for any other pertinent documents such as:
    • Related and/or companion documents
    • Prerequisite documents
    • Documents which provide background and/or context for this document
    • Documents that result from this document (e.g. a test plan or a development plan)
  • Define any important terms, acronyms, or abbreviations
  • Summarize (or give an abstract for) the contents of this document.

2. System Overview

2.1 General Description

Provide a general description of the software system including its functionality and matters related to the overall system and its design (perhaps including a discussion of the basic design approach or organization). Feel free to split this discussion up into subsections (and sub-subsections, etc ...). 

2.2 Overall Architecture Description

This section must contain the overall architecture description (you can find details describing the overall architecture description here).

2.3 Detailed Architecture

 

This should contain diagrams showing, at each level of the design, the data flow and control flow between the components.  Block diagrams, showing entities such as tasks and files, may also be used to describe the design.  The diagramming techniques used should be documented or referenced.

3. Design Considerations

This section describes many of the issues which need to be addressed or resolved before attempting to devise a complete design solution.

3.1 Assumptions and Dependencies

Describe any assumptions or dependencies regarding the software and its use. These may concern such issues as:

  • Related software or hardware
  • Operating systems
  • End-user characteristics
  • Possible and/or probable changes in functionality

3.2 General Constraints

Describe any global limitations or constraints that have a significant impact on the design of the system's software (and describe the associated impact). Such constraints may be imposed by any of the following (the list is not exhaustive):

  • Hardware or software environment
  • End-user environment
  • Availability or volatility of resources
  • Standards compliance
  • Interoperability requirements
  • Interface/protocol requirements
  • Data repository and distribution requirements
  • Security requirements (or other such regulations)
  • Memory and other capacity limitations
  • Performance requirements
  • Network communications
  • Verification and validation requirements (testing)
  • Other means of addressing quality goals
  • Other requirements described in the requirements specification

4. Graphical User Interface

  1. Provide an overview of the User Interface. 
    • Describe the general functionality of the system from the user’s perspective.
  2. Provide, in an organized way, the pictures (e.g., screen shots) of all the forms in the graphical user interface with a reference to the functional requirements they implement. You may use html to present the graphical user interfaces.
  3. For each form in the graphical user interface, provide:
    • The names of the controls and fields on that form,
    • The names of the events, methods, or procedures that cause that form to be displayed, and
    • The names of the events, methods, or procedures triggered by each control.
  4. Provide report formats (if any).  This is a description of major reports provided by the system.

5. Design Details

5.1 Class Responsibility Collaborator (CRC) Cards

You must include a CRC card for each class in your design.  You can find useful descriptions of CRC Cards at Ref 1, Ref 2 and Ref 3.  Ref 3 is particularly interesting because it is the paper where the CRC concept was first introduced and explained.  It is fairly short and very clear.

And of course, see Bjork’s Automated Teller Example.

5.2 Class Diagram

Your class diagrams must show each and every class in your design.  For a specific example, see the Automated Teller Example.

For a general description of the types of diagrams required here and in the following sections I recommend the following two references.

  1. UML Tutorial
  2. Practical UML™: A Hands-On Introduction for Developers (a reference from the reading list for Week 46 of last term in case you forgot).

5.3 State Charts

Use where appropriate.  See the Automated Teller Example.

5.4 Interaction Diagrams

A complete set of interaction diagrams (see references given in Sec. 5.2).  See the Automated Teller Example.

5.5 Detailed Design

Describe, in detail, the attributes and methods needed by each class (the second and third "compartments" of the representation for each class in a class diagram.) 

 

For each global data structure and database (if any) you must include the following information where applicable:

 

  1. Identify specific data elements and logical data groupings that are stored and processed by the design entities. 
  2. Outline data dependencies, relationships, and integrity rules in a data dictionary. 
  3. Specify the format and attributes of all data elements or data groupings.

 

For each method you must include the following information where applicable:

 

  1. Method Name
  2. Parameters, each documented with its intended use
  3. Return Value, suitably documented
  4. Informal description of what the procedure does
  5. Data structure and tables it accesses
  6. Pre-conditions: Assumptions the method can make about the state of the global data structures and database when it starts
  7. Validity Checks, Errors, and other Anomalous Situations: Validity checks the method must make about the state of the global data structures, the database, and its parameters, including the actions that must be taken when such a check fails.
  8. Post-conditions: The changes the method is supposed to make to the global data structures and database.
  9. Called by: The methods or events that call it
  10. Calls: The methods it calls and any events it causes.

 

See the Automated Teller Example for some guidance, although the presentation there is not as detailed as I require here.

 

One general note:  Make sure that you provide references back to your Requirements Document wherever possible.  You should include this to the greatest extent possible with each entry in the detailed design.  Finally, at the end of the section, you should have a complete index cross-referencing requirements in the RD with the different elements of the design.  I should be able to see where the functionality described in the Requirements Document is actually being implemented at a glance.

5.6 Package Diagram

For details see the Automated Teller Example.

6. Functional Test Cases

Each test case is in the form of a script that a system tester can follow to verify a specified functionality of the system.  Each test case must include the following:

  1. A description of the functionality being tested.
  2. A reference to the Requirements Document showing where the functionality was originally described.
  3. A clear description of the inputs (if any) to the tested functionality.
  4. A clear description of the expected output or other observable effects of the tested functionality.
  5. A step by step procedure that a tester can actually run on the system.

These test cases should cover the full range of functionality as described in the Requirements Document.

 

^Upp till Nadas kurser.

Sidansvarig: <rand@nada.kth.se>
Tekniskt stöd: <webmaster@nada.kth.se>