The software design creates the road map from which the software is coded. Once the requirements for the software are defined, they need to be divided into functional components that can be implemented ("coded") separately, yet work together to fulfill the goals and needs for which the software is being written. The software design defines how to segment the software into components and units, which are useful for modularizing like functionality, reuse, etc. "The process of design provides the structure for converting the requirements into the final code. Where the requirements state what must be done, the design provides how it will be done."
The goal is to create "a meaningful engineering representation of something that is to be built...a higher-level interpretation of what will actually be implemented in the source code." This representation, which traces back to the requirements, is the software design.
Per NPR 7150.2, "Software design is the process of defining the software architecture, components, modules, interfaces, and data for a software system to satisfy specified requirements. The software architecture is the fundamental organization of a system embodied in its components, their relationships to each other and to the environment, and the principles guiding its design and evolution. The software architectural design is concerned with creating a strong overall structure for software entities that fulfill allocated system and software-level requirements... Detailed design further refines the design into lower-level entities that permit the implementation by coding in a programming language."
Per NPR 7150.2, "Typical views captured in an architectural design include the decomposition of the software subsystem into design entities, computer software configuration items (CSCI), definitions of external and internal interfaces, dependency relationships among entities and system resources, and finite state machines. ...Typical attributes that are documented for lower-level entities include: identifier, type, purpose, function, constraints, subordinates, dependencies, interface, resources, processing, and data. Rigorous specification languages, graphical representations, and related tools have been developed to support the evaluation of critical properties at the design level. Projects are encouraged to take advantage of these improved design techniques to prevent and eliminate errors as early in the life cycle as possible." Projects can take advantage of existing designs when a similar project has already been completed, use frameworks which provide a base infrastructure on which to build, or be auto-coded using advanced design tools.
Software Design objectives
The software design description is a definition of the software architecture and the low-level requirements that will satisfy the high-level requirements. This data includes, as applicable:
- A detailed description of how the software satisfies the specified high-level requirements, including algorithms, data structures, interface descriptions, data configuration loads, update processes, software operational metrics, software and hardware fault management and how software requirements are allocated to processors and tasks.
- The description of the software architecture defining the software structure to implement the requirements.
- Descriptions of the software components, whether they are new or previously developed, and, if previously developed, reference to the baseline from which they were taken. This should include a detail description of the operating system, device drivers and board support package software.
- The input/output description, for example, a data dictionary, both internally and externally interfaces and data flows, including all direct hardware interfaces like the flight computer interface or application program interface or operation system interface.
- The data flow and control flow of the design.
- Input and output data conversions and units.
- Fault management approach and algorithm implementation.
- Sensor data qualification criteria and senor data disqualification criteria.
- Description and use of any open source components.
- Description and use of any reused software components.
- Description and use of any commercial off the shelf software components.
- Resource limitations, the strategy for managing each resource and its limitations, the margins, and the method for measuring those margins, for example, timing, fault messages, memory.
- Scheduling procedures and inter-processor/inter-task communications mechanisms, including time-rigid sequencing, preemptive scheduling and interrupts.
- Partitioning methods, means of preventing partition breaches, partitioning faults and partitioning metric data.
- Design methods and details for their implementation, for example, software updates, user-modifiable software or software parameters, redundancy management approach for the software design or multiple-version dissimilar software.
- Derived software requirements resulting from the software design process. Update the software requirements specification with the derived software requirements.
- If the software contains deactivated code or test code, a description of the means to ensure that the code cannot be enabled in the target computer.
- Security design features.
- Safety considerations addressed in the design, show traceable to all software hazards and software hazard migration steps.
- Rationale for those design decisions.
More detailed guidance for the content of the documents that capture software design, the Software Design Description (SDD) and the Interface Design Description (IDD), are found in SwDD and IDD in this Handbook.
The following roles may be involved in defining, documenting, and maintaining software design:
- Software Lead.
- Software engineers.
- Systems engineers.
- Software architects.
Capturing the software design
The software design is typically captured in three parts:
- Preliminary design – external design which describes the real-world design; this architectural design (SWE-057) reflects the requirements as allocated to software subsystems and defines the high level interfaces
- Detailed design (SWE-058) – further defines the subsystems by decomposing those subsystems into components and defining the internal interfaces
- As-built design – the final software design that was implemented in the code
When capturing software design, consider the following:
- Use a defined methodology such as structured analysis and design, object-oriented analysis and design, model-based development, as appropriate for the software being developed.
- Capture the reasoning behind design decisions (to support future design changes and maintenance).
- Document reuse plans.
- Capture a completed definition of the software architecture (see also Topic 7.7 - Software Architecture Description).
- Develop a preliminary database design description, as applicable.
- Document the selected operating system and development language.
- Trace software requirements into the design, as well as tracing the design back to requirements (i.e., bidirectional).
- Define and document the functional interfaces between all components.
- Identify and document shared data within the software.
- Capture the design in a manner that is maintainable (the design needs to be updated as it matures during development and changes through product maintenance efforts).
- Identify software safety design features and methods used to implement the software safety requirements.
- Capture the IT security features.
- Capture each software subsystem's "software classification (per NPR 7150.2), its safety classification (per NASA-STD-8719.13B, NASA Software Safety Guidebook), the rationale for the classifications" ; a matrix could be used to capture this information.
- Consider the "Design verification approach, e.g., prototyping, inspection, peer review."
If a software item is developed in multiple builds, its design may not be fully defined until the final build. Software design required for each build is the design necessary to meet the software item requirements to be implemented in that build.
While the software design is based primarily on the software requirements, the following documents may also influence the software design. As applicable, these documents need to be considered as sources of reasons for design decisions:
- Operational concepts and scenarios.
- Trade studies.
- System and hardware requirements.
- Processor and communication specifications.
- Hardware design documents, including interface control documents (ICDs).
- Software requirements rationale.
- Design standards.
- Design selection criteria (to help choose a design or design element from multiple options).
- "Sources for design concepts include, but are not limited to, customer input, brainstorming, collective experience and supplier knowledge."
Useful Methods and Techniques
The following methods and techniques may be helpful when documenting and maintaining the software design:
- Structured analysis and design.
- Formal methods and model-based development.
- Functional decomposition and object-oriented design, including the use of design diagrams, structure charts, and associated documentation.
- Design walk-throughs and peer reviews.
- Design inspections.
- Reuse verification ("determining which of the existing software components specified in the reuse proposal should be integrated into the new system design").
- Prototyping and demonstrations.
- Performance modeling.
- Entity relationship models.
- Design patterns.
Some general guidance to follow when capturing and maintaining the software design includes:
- Include a legend for any diagrams that assign specific meaning to shapes, colors, line styles, etc.
- Have the documented design and its updates reviewed at key life-cycle milestone reviews [e.g., Preliminary Design Review (PDR), Critical Design Review (CDR), Test Readiness Review (TRR)].
- Have the documented design reviewed after it has been updated at any time in the life cycle.
- Include software safety personnel in the design review process.
- Update the requirements as design decisions are made, including adding requirements derived from design decisions.
- Keep the design current with changes to the requirements.
- Perform software peer reviews/inspections (SWE-087) of the design prior to moving to implementation (coding), as applicable.
The NASA Software Architecture Review Board, a software engineering sub-community of practice accessible on the NASA Engineering Network, is a good resource of software design information including sample documents, reference documents, and expert contacts.
NASA users should consult Center Process Asset Libraries (PALs) for Center-specific guidance, templates, and examples related to documenting the software design. Similar information for the Agency can be found in Software Processes Across NASA (SPAN), accessible to NASA users from the SPAN tab in this Handbook.
Additionally, guidance related to software design may be found in Topic 7.7 - Software Architecture Description and the following related requirements in this handbook: