1. Requirements

3.2.3 The project shall develop, record, and maintain a detailed design based on the software architectural design that describes the lower-level units so that they can be coded, compiled, and tested.

1.1 Notes

NPR 7150.2, NASA Software Engineering Requirements, does not include any notes for this requirement.

1.2 Applicability Across Classes

Classes F and G are labeled with "X (not OTS)." This means that this requirement does not apply to off-the-shelf software for these classes.

Classes C thru E and Safety Critical are labeled with "SO." This means that this requirement applies to the safety-critical aspects of the software.

2. Rationale

The detailed design, as an extension of the architectural design, provides detailed descriptions of the lowest level of software components. The detailed design provides enough information for someone to create code without significant interpretation. The design maintains consistency with design standards, programming language dependencies and external interfaces. Any redesign or maintenance of the software work product anywhere in the life cycle must also conform to the detailed design to avoid software performance degradation or error issues. The documentation of the design and descriptions of the lower-level components enables other members of the team to base their activities on previous versions to assure successful coding, compiling, and testing.

Recording, which may be textual, visual, or a combination, allows for the design to be inspected to ensure that the design meets the project's requirements and architectural design. The design also needs to be maintained to assure updates are completed, and to assist in future modifications to the software.

3. Guidance

NPR 7150.2 describes the software detail design activity, which is preliminary at project PDR (Preliminary Design Review) and baselined at CDR (Critical Design Review) (see SWE-019 and 7.08 - 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 7.09 - 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 from the Software Technology Support Center 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 SWE-102)?
• Do you have a software architecture definition document (see SWE-111)?
• Do you have a systems requirements specification (see SWE-109)?
• 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 (Computer-Aided Software Engineering) tools being used to assist and document the design effort (see SWE-136)?
• Does your design process include a robust configuration control process (see SWE-103)?
• Is the design effort being properly documented? (see SWE-111) 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 SWE-102)?
• Are the characteristics of all data elements identified (type, format, size, units, and others important to the project) (see SWE-110)?

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.
• Libraries 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" (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" (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" (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 SWE-111).
• Software Interface Design Description document (see SWE-112).
• Software User Manual (see SWE-112).

When documenting elements of the detailed design include information such as

• Identifier and types.
• Purpose and function.
• Constraints.
• Subordinates and dependencies.
• Interfaces.
• Resources.
• 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 UML (Unified Modeling Language) 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.

4. Small Projects

The completion of a software development project inherently means that the detailed design activities are conducted and completed. Smaller projects may benefit by limiting the development or use of original or unique tools and environments in the detailed design process. Smaller projects may consider using previously developed coding standards and documentation processes, if applicable, rather than developing their own. These standard applications may be available in the Center's Process Asset Library (PAL) or in the software PALs of other Centers.

5. Resources

6. Lessons Learned

The NASA Lesson Learned database contains the following lessons learned related to software design:

• MER Spirit Flash Memory Anomaly (2004). Lesson Number 1483: Enforce Design Guidelines: "A severely compressed flight software development schedule may prevent the achievement of a full understanding of software functions. During the MER (Mars Exploration Rover) software development process there was a continuous reprioritization of activities and focus. One impact of this dynamic process was that only the highest priority flight software issues and problems could be addressed, and memory management problems were viewed as a low risk." Recommendation No. 1 states to "Enforce the project-specific design guidelines for COTS (Commercial Off the Shelf) software, as well as for NASA-developed software. Assure that the flight software development team reviews the basic logic and functions of commercial off-the-shelf (COTS) software, with briefings and participation by the vendor." ⁵⁵⁷

• Software Design for Maintainability. Lesson Number 0838: Impact of Non-Practice: "Because of increases in the size and complexity of software products, software maintenance tasks have become increasingly more difficult. Software maintenance should not be a design afterthought; it should be possible for software maintainers to enhance the product without tearing down and rebuilding the majority of code." ⁵²⁶

• Mars Observer Inertial Reference Loss. Lesson Number 0310: Design for Maintenance, Lesson Learned No. 4: "Design flexibility of the flight computer and software is critical to the ability to uplink software patches for the correction of unexpected in-flight spacecraft anomalies." ⁵⁰¹

• ADEOS-II NASA Ground Network (NGN) Development and Early Operations – Central/Standard Autonomous File Server (CSAFS/SAFS) Lessons Learned. Lesson Number 1346: Use of COTS products: "Match COTS tools to project requirements. Deciding to use a COTS product as the basis of system software design is potentially risky, but the potential benefits include quicker delivery, less cost, and more reliability in the final product. The following lessons were learned in the definition phase of the [software] development.
  • "Use COTS products and re-use previously developed internal products.
  • "Create a prioritized list of desired COTS features.
  • "Talk with local experts having experience in similar areas.
  • "Conduct frequent peer and design reviews.
  • "Obtain demonstration versions of COTS products.
  • "Obtain customer references from vendors.
  • "Select a product appropriately sized for your application.
  • "Choose a product closely aligned with your project's requirements.
  • "Select a vendor whose size will permit a working relationship.
  • "Use vendor tutorials, documentation, and vendor contacts during COTS evaluation period." ⁵⁵⁰

• Fault Tolerant Design. Lesson Number 0707: "Systems which do not incorporate FTD (Fault Tolerant Design) as a part of their development process will experience a higher risk of a severely degraded or prematurely terminated mission, or it may result in excessively large weight volume, or high cost to achieve an acceptable level of performance by using non-optimized redundancy or overdesign...Incorporate hardware and software features in the design of spacecraft equipment which tolerate the effects of minor failures and minimize switching from the primary to the secondary string. This increases the potential availability and reliability of the primary string." ⁵¹⁷