NPR 7150.2 describes the software detail design activity, which is preliminary at project Preliminary Design Review (PDR) and baselined at Critical Design Review (CDR) (see SWE-019 and topic 7.8 - Maturity of Life-Cycle Products at Milestone Reviews), as occurring after the completion of the software architectural design process. This in turn is the "process of defining the architecture, components, modules, interfaces, and data" of a system or component. The software work product detailed design, which flows out of the software architectural definition (see SWE-057) and the preliminary design phase, is focused on defining the lower-level components, modules and interfaces, and bringing them to a level of maturity sufficient to begin coding activities.
3.1 Design Readiness
A review of the success criteria for Preliminary Design Reviews (PDRs) (see topic 7.9 - Entrance and Exit Criteria) by the software development team will assure the readiness to proceed to the detailed design phase. The software development team then decides which criteria are necessary for the project.
An example checklist for determining readiness to begin software detailed design activities is shown below. It suggests "readiness" questions the software team leader can ask before starting and continuing into and during the detailed design activity. This checklist also assists the leader in understanding the software design issues of the project. If the leader cannot answer a question affirmatively, the project leadership must determining whether or not they are ready to proceed.
Consider the following before starting the detailed design:
- Do you have a well-documented software development process (see SWE-036)?
- Do you understand what is to be performed and produced in each phase of the design process (see SDP-SMP)?
- Do you have a software architecture definition document (see SwDD)?
- Do you have a systems requirements specification (see SRS)?
- Are you familiar with the methods, tools, standards, and guidelines for your project (see SWE-061)?
- Are applicable and efficient design methods being implemented on your project?
- Are the developers trained and experienced in the chosen development process and methods (see SWE-017)?
- Is software reuse being considered throughout the development effort (see SWE-027)?
- Is off the shelf software being considered for use on the project (see SWE-027)?
- Has an analysis of alternatives been completed?
- Is the selection of architecture and design methods based on system operational characteristics?
Consider the following during detailed design:
- Are CASE tools being used to assist and document the design effort (see SWE-136)?
- Does your design process include a robust configuration control process (see SCMP)?
- Is the design effort being properly documented? (see SwDD) Is it adequate but not burdensome?
- Is your team committed to following the design process?
- Are all requirements traceable to design elements (see SWE-059)?
- Are all design elements traceable to specific requirements?
- Have all software work products (components, units, systems) been identified (see SDP-SMP)?
- Are the characteristics of all data elements identified (type, format, size, units, and others important to the project) (see SDD)?
3.2 Coding Standards and Processes
The design activity proceeds from the software architectural definition (see SWE-057). The key decomposition and dependency features and the design/coding standards specified or begun during the development of the software architecture are then maintained and/or completed during the design phase of the software development life cycle.
The software development team reviews and maintains the selected coding standards (see SWE-061) that were established for all the languages being used, documented or referenced in the project's software documentation.
The initial steps in developing the software detailed design involve the definition of functions, inputs, and outputs for each component.
In some projects that employ component-based development, the components may be pre-existing and fixed, or customizable in only a limited way. The design focus then lies on integrating existing components to form new systems.
The software development team can describe the design by using a programming design language or by using pseudo code.
Consideration can be given to the reuse of software for all or some major components, such as:
- Application generators.
- Database management systems.
- Human-computer interaction utilities.
- Mathematical utilities.
- Graphical utilities.
- Library modules.
- Library modules with shells built to standardize interfaces (e.g., for error handling) and enhance portability.
Once the final functions are determined, they are coded into the selected programming language. Although the decomposition activities nominally occur during the software architecting activities, the software development team must revisit the architecture if one or more of the decomposition criteria will not be satisfied in the proposed detailed design:
- Will the module have too many statements?
- Will the module be too complex?
- Does the module have low "cohesion" (a measure of how strongly related each piece of functionality expressed by the source code of a software module is)?
- Does the module have high "coupling" (the degree to which each program module relies on each other in the other modules)?
- Does the module contain similar processing to other modules?
3.3 Design Considerations
A best practice is to use modularity in the design, with minimal coupling between components and maximum cohesion within each component. Modular designs are more understandable, reusable and maintainable than designs consisting of components with complicated interfaces and poorly matched groupings of functions. Each level of a design is best described by including only the essential aspects, and omitting the inessential detail. This means the design description includes the appropriate degree of "abstraction" (Abstraction captures and represents only those details about an object that are relevant to the current perspective). This enhances understandability, adaptability and maintainability.
Component-based software engineering emphasizes the use of software components with distinct functionality that overlap as little as possible. This a a reuse based approach for developing software for defining, implementing, and joining independent components into systems. Wikipedia is a good source for top level information on this approach.
The last step of detailed design (some may also say this is the first step of the coding phase) includes the initial steps for coding the process modules in preparation for unit testing. This transition from detailed design to the coding and test phase of the software life cycle occurs when the team begins to compile the developed work products into the programming language (see SWE-060 and SWE-061).
3.4 Detailed Design Documentation and Progress Reviews
As a part of this requirement, the software development team must record descriptions of the design down to the lower-level units. The main records or outputs of the detailed design phase are captured in the following set of project documents and work products:
- Software Design Description document (see SwDD).
- Software Interface Design Description document (see IDD).
- Software User Manual (see SUM).
When documenting elements of the detailed design include information such as
- Identifier and types.
- Purpose and function.
- Subordinates and dependencies.
- Processing characteristics and special needs, if any (e.g., required timing or special conditions necessary to execute).
- Other enabling data (e.g., products from the use of Universal Modeling Language (UML) or a tool such as Rhapsody).
Progress against plans is monitored by project management and documented at regular intervals in progress reports. Developers verify detailed designs in design reviews, level by level. Peer reviews and inspections of the software design before coding begins are used to eliminate design errors before conducting testing. See the guidance (SWE-087) related to software peer reviews and inspection of design items.
Two variations of software/peer reviews/inspections are useful:
- Design inspection.
- Scenario-based analyses.
In a design inspection, the software development team traces the logic of a module from beginning to end. In scenario-based analyses, component behavior is examined for responses due to specific inputs.
3.5 Design Maintenance
Once these detailed designs are created, they are maintained to reflect current project status, progress, and plans, which will change over the life of the project. If requirements changes occur, or if the design approach proves faulty, the software architecture design may need to be changed before continuing with the detailed design of the software work products. When requirements change (SWE-071), software designs, test plans, procedures and the resulting test reports may also need to be updated or revised to reflect the changes.
Just as the project team ensures that initial detailed designs and their reports are reviewed and approved before use, the team also ensures that updates are also reviewed and approved following project procedures. (See SWE-080)
The software development team must continue to maintain accurate and current software design descriptions throughout the operation and maintenance phases of a project.
The Software Architecture Review Board , a software engineering sub-community of practice, is a good resource of software design information including sample documents, reference documents, and expert contacts.
Consult Center Process Asset Libraries (PALs) for Center-specific guidance and resources related to best practices, tools, and design standards for software detailed design activities.