diff --git a/process/process_areas/implementation/guidance/implementation_guideline.rst b/process/process_areas/implementation/guidance/implementation_guideline.rst index 6673691d0a..a82a9e1514 100644 --- a/process/process_areas/implementation/guidance/implementation_guideline.rst +++ b/process/process_areas/implementation/guidance/implementation_guideline.rst @@ -18,7 +18,7 @@ Guideline .. gd_guidl:: Implementation Guideline :id: gd_guidl__implementation :status: valid - :version: 1 + :version: 2 :complies: std_req__iso26262__software_744[version==1], std_req__iso26262__software_841[version==1], std_req__iso26262__software_842[version==1], @@ -44,11 +44,20 @@ Detailed description which steps are need for implementation. #. Consult which programming languages, design/coding guidelines and tools are used for Software development according the rules given in the project specific :need:`SW development Plan `. -#. Create a Detailed Design by using the template :need:`gd_temp__detailed_design`. - Based on the :need:`Component Requirements ` and the - :need:`Component Architecture `, the components are broken down into smaller, - independent units that can be tested separately during the unit testing phase. - The detailed design shall be so exact that test and implementation can be run simultaneously. +#. Create a Detailed Design. Based on the :need:`Component Requirements ` + and the :need:`Component Architecture `, the component is broken down into + smaller, independent units that can be tested separately during the unit testing phase. + A detailed design shall exist for every unit. It is captured primarily in the source code + itself (unit interfaces and contracts, e.g. public API headers, trait or function signatures, + and source code comments). A separate detailed design document following the template + :need:`gd_temp__detailed_design` including static and dynamic views is **optional** and is + only created where it helps to explain complex components or a large number of unit + interactions (see :need:`doc_concept__imp_concept`). The detailed design shall be so exact, + that test and implementation can be run simultaneously. +#. Document and justify the detailed design decisions, in particular those that shape the + decomposition of the component into units. The rationale shall be captured close to the design, + i.e. in the source and header files (e.g. as doxygen-style comments) and, where applicable, in the + detailed design documentation (see :need:`doc_concept__imp_concept`). #. Implement the source code, by using the coding guidelines given within the project specific :need:`SW development Plan ` for the programming languages in your project. #. Create a pull request for your change. #. Detail Design and Code Inspection is done to review the code of the software and detect errors in it. See the detailed design and code :need:`inspection checklist ` for evaluation criteria. @@ -58,11 +67,43 @@ Detailed description which steps are need for implementation. #. Create a follow up ticket if not all findings could be fixed. +Basis for Unit Testing +====================== + +The basis (test oracle) for unit testing is the **detailed design of the unit**, i.e. the +unit's specified interfaces and behaviour as documented in the source code (public API +headers, trait or function signatures and their contracts). The source code is the object +under test, not the reference against which it is tested. + +Requirements are owned by the **component**, not by individual units, and there is no +formal allocation of requirements to units. The component requirements are distributed +across the units implicitly by the detailed design, and they are verified collectively by +the units and primarily by the component integration tests (see :need:`wp__component_arch` +and the verification process area). Separate requirements at unit granularity are therefore +**not** required. + +Unit tests thus verify the detailed design of the unit. Only in the exceptional case where +a single unit fully realises a component requirement may the corresponding unit test cover +and link to that component requirement directly. + Traceability ============ -The detailed design is created by using the template :need:`gd_temp__detailed_design`. In the template -the static and the dynamic view for unit interactions is described. +The traceability of a component to its units is achieved primarily through naming +conventions: the decomposition of a component into its units is mainly described by the +directory and file name structure. Each component (and sub-component) maps to a namespace +and thus to a directory, its units are represented by the corresponding source and header +files within that directory, and sub-components are reflected by nested sub-directories so +that the folder hierarchy mirrors the decomposition of the component into sub-components +and units. Units therefore belong to their component and inherit the accordance to the +architecture from their location (see :need:`doc_concept__imp_concept`). Unit tests and +the detailed design are implicitly related by file naming and header inclusion, so no +additional explicit linking is required for these. + +A static and a dynamic view for unit interactions are optional and are only added when +they help to explain complex components or a large number of unit interactions. If such +diagrams are provided, they are linked to the architecture and the component requirements +as shown below. Traceability from requirements to units is established implicitly through the verification work products: :need:`unit tests ` and :need:`component integration tests ` reference specific requirement IDs and exercise @@ -75,7 +116,7 @@ are verified through tests that exercise specific units. :width: 30% :name: static_view_fig -The static diagram satisfies the architecture and implements the requirements of the related component. The static diagram includes Unit1+2. +If used, the static diagram satisfies the architecture and implements the requirements of the related component. The static diagram includes Unit1+2. .. figure:: _assets/dynamic_view.drawio.svg @@ -83,14 +124,14 @@ The static diagram satisfies the architecture and implements the requirements of :width: 30% :name: dynamic_view_fig -The dynamic diagram satisfies the architecture and implements the requirements of the related component. +If used, the dynamic diagram satisfies the architecture and implements the requirements of the related component. .. figure:: _assets/dd_traceability.drawio.svg :align: center :width: 30% :name: dd_traceability_fig -The unit description will be generated automatically based on the comments in the source code and from the interface description. +The unit description is provided by the interface documentation and the comments in the source code itself. Detailed Design Guidance ======================== @@ -124,16 +165,20 @@ Units within the Component -------------------------- The relationship between a unit and its parent component is established implicitly through the -**file path** - each component has its own directory, and units residing within that directory -belong to it and therefore align with the architecture. A separate static diagram per unit is -**not required**; the unit's attributes and behaviour are documented in the source code itself, -as the source code is sufficiently self-explanatory and adheres to the design principles outlined -in the development plan. +**file path**: the decomposition of a component into its units is mainly described by the directory +and file name structure. Each component (and sub-component) has its own directory, its units are +represented by the corresponding source and header files within that directory, and sub-components +are reflected by nested sub-directories so that the folder hierarchy mirrors the decomposition of +the component into sub-components and units. Units therefore belong to their component and inherit +the accordance to the architecture from their location. A separate static diagram +per unit is **not required**; the unit's attributes and behaviour are documented in the source +code itself as the source code is sufficiently self-explanatory and adheres to the design principles outlined in the development plan. + +This is sufficient for ASIL B compliance per :need:`ISO 26262-6 §8 `, as the structural decomposition +is evident from the directory layout and the component-level static view of the architecture already captures the +relevant unit relationships. -However, for components with complex interactions or a large number of units, a textual description, -a static or dynamic view can be beneficial for understanding the overall structure and relationships -between units. The developer may choose to add an additional unit-level description, static and dynamic -view if this helps explain the source code better. +However, for components with complex interactions or a large number of units, a static view can be beneficial for understanding the overall structure and relationships between units. The developer may choose to add a additional unit-level static and dynamic view if they believe it helps to explain the source code better. It is important that the naming of the units, their interfaces and functions in any diagrams or descriptions matches the naming in the source code to ensure traceability. This means the diagrams @@ -143,18 +188,21 @@ introduce new terminology or concepts that are not present in the code. Design Principles of the Units `````````````````````````````` -The unit design and implementation should target quality attributes like simplicity, modularity and encapsulation, -using project-defined coding guidelines and static analysis tooling appropriate for the language -in use as specified in the software development plan. +The unit design shall achieve quality attributes (like simplicity, modularity, and encapsulation) which shall be enforced through coding guidelines and static analysis tooling appropriate for the programming language in use (e.g. MISRA C for C/C++, Clippy lints for Rust) as specified in the project development plan to fulfill the guidelines :need:`ISO 26262-6 §8.4.5, Table 6 ` and :need:`ASPICE SWE.3/SWE.4` requirements. + +For safety-related (ASIL) units, the design and coding principles for software unit design and +implementation of :need:`ISO 26262-6 §8.4.5, Table 6 ` shall be +applied. -For ASIL B components, the software development plan shall mandate compliance with the design principles -specified in ISO 26262-6 §8.4.5 Table 6. These principles shall be enforced through project-specific -coding guidelines and automated static analysis tooling. +These principles are not enforced manually only: the project's coding guideline together with the +static and dynamic code analysis defined in the project development plan (e.g. MISRA C for C/C++, +Clippy lints for Rust) shall enforce them for ASIL units. For QM units the same activities apply, +whereas the ISO 26262 specific principles above are binding only for safety-related units. -The **source code** itself should be self-documenting with meaningful naming and structure. -**Code comments** may be used where the logic is not self-evident and to provide rationale. +The **source code** itself shall be self-documenting with meaningful naming and structure. +**Code comments** may be used where the logic is not self-evident and to give an rationale. These comments, along with commit messages, and any additional documentation accompanying the -source code should use natural language. +source code shall use natural language. The interface documentation of a software unit is part of the source code (e.g. public API headers, trait definitions, or documented function signatures). If interfaces of the units are also interfaces diff --git a/process/process_areas/implementation/guidance/implementation_process_reqs.rst b/process/process_areas/implementation/guidance/implementation_process_reqs.rst index 0f9159a9fd..bd2636538b 100644 --- a/process/process_areas/implementation/guidance/implementation_process_reqs.rst +++ b/process/process_areas/implementation/guidance/implementation_process_reqs.rst @@ -15,6 +15,22 @@ Process Requirements #################### +.. gd_req:: Design Decision Rationale + :id: gd_req__impl_design_decision + :status: valid + :version: 1 + :tags: manual_prio_1, mandatory + :satisfies: wf__sw_detailed_design[version==1] + :complies: std_req__iso26262__software_842[version==1], + std_req__iso26262__support_6421[version==1], + std_req__iso26262__support_6425[version==1], + std_req__aspice_40__SWE-3-BP2[version==1] + + The detailed design decisions shall be documented and justified, in particular those + that shape the decomposition of a component into its units. The rationale shall be + captured close to the design, i.e. in the source and header files (e.g. as + doxygen-style comments) and, where applicable, in the detailed design documentation. + Please notice, that detail design description files (within MarkDown or RestructuredText) are optional. Also diagrams are optional, but if they are created, they shall have the following attributes to ensure consistency and traceability. @@ -22,14 +38,19 @@ Also diagrams are optional, but if they are created, they shall have the followi :id: gd_req__impl_static_diagram :status: valid :version: 1 - :tags: manual_prio_1, mandatory + :tags: manual_prio_1, optional :satisfies: wf__sw_detailed_design[version==1] :complies: std_req__iso26262__software_843[version==1], std_req__iso26262__software_844[version==1], std_req__iso26262__software_845[version==1], std_req__aspice_40__SWE-3-BP1[version==1] - The static diagram shall represent the units and their relationships using UML notations. + A static diagram is optional. The decomposition of a component into its units is + primarily represented by the directory and file structure (see + :need:`doc_concept__imp_concept`), so a static diagram is only added when it helps to + explain complex components or a large number of unit interactions. + If a static diagram is provided, it shall represent the units and their relationships + using UML notations, and it shall provide the attributes and linkages defined below. Diagram Attributes ------------------ diff --git a/process/process_areas/verification/verification_workflows.rst b/process/process_areas/verification/verification_workflows.rst index 2b768566dc..1b4c7202d4 100644 --- a/process/process_areas/verification/verification_workflows.rst +++ b/process/process_areas/verification/verification_workflows.rst @@ -52,9 +52,10 @@ For a detailed explanation of workflows and their role within the process model, #. Check the detailed design of the component. Create a test for every interface of the unit showing at least every flow in dynamic diagrams. - #. Follow the detailed design to the component requirements and test these requirements. + #. Only in the exceptional case where a single unit fully realises a component requirement, + follow the detailed design to that component requirement and cover it with the unit test. #. Fill in the test attributes based on the previous steps and provide a description. - #. Link the test against detailed design or component requirement. + #. Link the test against the detailed design and, in the exceptional case above, the component requirement. .. workflow:: Create/Maintain Component Integration Test :id: wf__verification_comp_int_test