From db1fad4bf32daea9ed41a9b3b26e82d1704e9577 Mon Sep 17 00:00:00 2001 From: "jhr2hi@bosch.com" Date: Mon, 27 Jul 2026 16:54:08 +0200 Subject: [PATCH 1/3] improve implementation --- .../guidance/implementation_guideline.rst | 62 ++++++++++++++++--- .../guidance/implementation_process_reqs.rst | 25 +++++++- .../implementation/implementation_concept.rst | 26 +++++++- .../verification/verification_workflows.rst | 5 +- 4 files changed, 101 insertions(+), 17 deletions(-) diff --git a/process/process_areas/implementation/guidance/implementation_guideline.rst b/process/process_areas/implementation/guidance/implementation_guideline.rst index c81b98325d..7adaef2f1b 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: 3 :complies: std_req__iso26262__software_744[version==1], std_req__iso26262__software_841[version==1], std_req__iso26262__software_842[version==1], @@ -35,10 +35,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`. - In this step, 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 doxygen-style 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. @@ -48,18 +58,50 @@ 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. .. figure:: _assets/static_view.drawio.svg :align: center :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 @@ -67,11 +109,11 @@ 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. diff --git a/process/process_areas/implementation/guidance/implementation_process_reqs.rst b/process/process_areas/implementation/guidance/implementation_process_reqs.rst index 007ef2ea50..3d9c0a11ad 100644 --- a/process/process_areas/implementation/guidance/implementation_process_reqs.rst +++ b/process/process_areas/implementation/guidance/implementation_process_reqs.rst @@ -15,18 +15,39 @@ 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. + .. gd_req:: Static Diagram for Unit Interactions :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 unit 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/implementation/implementation_concept.rst b/process/process_areas/implementation/implementation_concept.rst index 6ccfba0225..fb9c100329 100644 --- a/process/process_areas/implementation/implementation_concept.rst +++ b/process/process_areas/implementation/implementation_concept.rst @@ -86,13 +86,17 @@ 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 inherit the accordance to the architecture. A separate static diagram +**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 already captures the +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 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. @@ -102,6 +106,22 @@ Design Principles of the Units 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, in particular: + +- one entry and one exit point per function, +- initialization of variables before use, +- no (or justified) use of dynamic objects and dynamic memory allocation, +- limited use of pointers and no implicit type conversions, +- no hidden data flow or control flow, +- no unconditional jumps and no (or bounded) recursion. + +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 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 diff --git a/process/process_areas/verification/verification_workflows.rst b/process/process_areas/verification/verification_workflows.rst index 97d5a17e58..38a084f02d 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 From b3242fe0cc262d548e89cd3dedf041c4c3ce647f Mon Sep 17 00:00:00 2001 From: "jhr2hi@bosch.com" Date: Tue, 28 Jul 2026 07:41:48 +0200 Subject: [PATCH 2/3] correct number --- .../implementation/guidance/implementation_guideline.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/process/process_areas/implementation/guidance/implementation_guideline.rst b/process/process_areas/implementation/guidance/implementation_guideline.rst index 7adaef2f1b..fd797dad36 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: 3 + :version: 2 :complies: std_req__iso26262__software_744[version==1], std_req__iso26262__software_841[version==1], std_req__iso26262__software_842[version==1], From cac151a6921b714e1ae1f93db3e39c409beab7be Mon Sep 17 00:00:00 2001 From: "jhr2hi@bosch.com" Date: Tue, 28 Jul 2026 08:01:12 +0200 Subject: [PATCH 3/3] fix review findings --- .../implementation/guidance/implementation_guideline.rst | 2 +- .../implementation/implementation_concept.rst | 9 +-------- 2 files changed, 2 insertions(+), 9 deletions(-) diff --git a/process/process_areas/implementation/guidance/implementation_guideline.rst b/process/process_areas/implementation/guidance/implementation_guideline.rst index fd797dad36..66f33a9753 100644 --- a/process/process_areas/implementation/guidance/implementation_guideline.rst +++ b/process/process_areas/implementation/guidance/implementation_guideline.rst @@ -40,7 +40,7 @@ Detailed description which steps are need for implementation. 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 doxygen-style comments). A separate detailed design document following the template + 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, diff --git a/process/process_areas/implementation/implementation_concept.rst b/process/process_areas/implementation/implementation_concept.rst index fb9c100329..617054d596 100644 --- a/process/process_areas/implementation/implementation_concept.rst +++ b/process/process_areas/implementation/implementation_concept.rst @@ -108,14 +108,7 @@ The unit design shall achieve quality attributes (like simplicity, modularity, a 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, in particular: - -- one entry and one exit point per function, -- initialization of variables before use, -- no (or justified) use of dynamic objects and dynamic memory allocation, -- limited use of pointers and no implicit type conversions, -- no hidden data flow or control flow, -- no unconditional jumps and no (or bounded) recursion. +applied. 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++,