Software Design Document (SWDD)

Definition

Software Design Document (SWDD)

the design work product that officially documents the design of one or more software components

Objectives

The typical objectives of a software design document are to formally document the design of:

• Individual packages.
• Software units (modules) within the packages.

Benefits

The typical benefits of a software design document include:

• The designs of the individual packages and modules (e.g., classes, class methods, procedures) within one or more software components are localized so that they can be properly evaluated and maintained.
• Well documented code is more easy to reuse.
• Additions to the development team can be transitioned in more smoothly because they can get up to speed with standard documentation and not rely on word of mouth.
• It captures important design decisions such as responsibilities that drive the implementation.
• It supports:
  • Software integration testing of the package by describing its interface, structure, and behavior.
  • Unit testing of the associated modules by describing their interfaces.

Contents

The typical contents of a software design document are:

• Package Design:
  • Package Name and Purpose
  • Package Responsibilities
  • Package Interfaces
  • Package Contents
    (e.g., list of component classes and packages, class diagram, collaboration diagram, sequence diagrams)
  • Unit Design:
    • Unit Name and Abstraction (Definition)
    • Unit Responsibilities
    • Unit Interfaces
    • Unit Contents:
      • Class Attributes:
        • Name
        • Type (potentially by reference to a data dictionary)
        • Visibility
      • Class Invariants (if any)
      • Class Methods or Procedures:
        • Method Name
        • Method Purpose
        • Method Signature:
          • Parameters including names, types including ranges (if restricted), and data flow (in, out, in/out)
          • Exceptions raised and handled
        • Method Preconditions and Postconditions
        • Method Structure (if appropriate)
      • Class Exceptions:
        • Exception Name and Abstraction (Definition)
        • Exception Type
    • Unit State Model (if appropriate)
• Appendices:
  • Major Issues
  • TBDs
  • Assumptions

Stakeholders

The typical stakeholders of a software design document are:

• Producers:
  • Software Development Team
• Evaluators:
  • Software Inspection Team
• Approvers:
  • Technical Leader
  • Project Manager
  • Customer Representative
• Maintainer:
  • Software Development Team
• Users:
  • Software Development Team, which use the software design document to drive the implementation, unit testing, and package integration testing of the software.

Phases

A software design document is typically produced during the following phases:

Preconditions

A software design document can typically be started if the following preconditions hold:

• The initiation phase is started.
• The software development team is staffed and trained in the design tasks.
• The associated conventions (e.g., content and format standard, template) exist.
• Initial versions of the following input work products exist and contain relevant information that is relatively stable.

Inputs

A software design document typically has the following inputs:

• Work Products:
  • System Requirments Specification
  • Domain Model Document
  • Glossary
  • System Architecture Document
  • Software Architecture Document
• Stakeholders:
  • Software Architect

Guidelines

• The contents above have been written under the assumption of an object-oriented design approach which implies that units are classes. The unit design documentation should be modified to that used to describe class methods if a procedural language is to be used.
• An endeavor can produce:
  • A single software design document covering all software packages of all software components.
  • Multiple software design documents:
    • One software design document for each software component.
    • One software design document for each software package.
  • No software design document (e.g. if the designs of the individual software units are captured in some other form such as Javadoc).
• Software design documents should be living documents that evolve as the software design is iteratively and incrementally produced and maintained.
• Due to the incremental and iterative nature of modern software development cycles, it can be extremely difficult, time-consuming, and expensive to ensure that the software design documents remain consistent with the resulting source code implementations without use of an integrated development environment (IDE) that supports forward and reverse engineering between the design and the code.
• Much of the contents of the software design document can (and should) be stored in the form of comments in the relevant package and unit source code. If a parallel development cycle is used in which software design and programming occur concurrently and if programming standards require the documentation of much of the design in the form of comments, then much of the textual information in the software design document can be safely removed because it is redundant. In this case, the software design document primarily contains diagrams and more summary information.
• The design of user-interface modules can be stored in the human-interface design document and included in the software design document by reference.
• The design of data types can be stored in the data dictionary or database design document and included in the software design document by reference.
• The software design document can be a:
  • Manually or automatically generated paper document.
  • Electronic document
  • A logical collection of its contents stored by an upperCASE tool.
• The organization (content and format) of the software design document(s) should mirror the structure of the associated software components. The quality of the document(s) will be improved to the extent that the components are partitioned into cohesive, loosely-coupled, modular packages and classes that exhibit proper encapsulation and information hiding.
• On small software-only endeavors, the software design document and the system architecture document may be combined into a single document.

Conventions

The software design document is typically constrained by the following conventions:

• Content and Format Standard
• MS Word Template
• XML DTD Template
• Inspection Checklist

Examples

• Example Software Design Document