Skip to content

improve implementation #751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RolandJentschETAS merged 4 commits into from
Jul 28, 2026
+103 −33
Merged

improve implementation #751

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
db1fad4
improve implementation
RolandJentschETAS Jul 27, 2026
b3242fe
correct number
RolandJentschETAS Jul 28, 2026
cac151a
fix review findings
RolandJentschETAS Jul 28, 2026
81e5473
Merge remote-tracking branch 'origin/main' into improvement_better_im…
RolandJentschETAS Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 77 additions & 29 deletions process/process_areas/implementation/guidance/implementation_guideline.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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],
Expand All @@ -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 <wp__sw_development_plan>`.
#. Create a Detailed Design by using the template :need:`gd_temp__detailed_design`.
Based on the :need:`Component Requirements <wp__requirements_comp>` and the
:need:`Component Architecture <wp__component_arch>`, 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 <wp__requirements_comp>`
and the :need:`Component Architecture <wp__component_arch>`, 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 <wp__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 <doc__feature_name_req_inspection>` for evaluation criteria.
Expand All @@ -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 <wf__verification_unit_test>` and :need:`component integration tests <wf__verification_comp_int_test>` reference specific requirement IDs and exercise
Expand All @@ -75,22 +116,22 @@ 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
:align: center
: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
========================
Expand Down Expand Up @@ -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 <std_req__iso26262__software_841>`, 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
Expand All @@ -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 <std_req__iso26262__software_845>` and :need:`ASPICE SWE.3/SWE.4<std_req__aspice_40__SWE-3-BP3>` 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 <std_req__iso26262__software_845>` 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
Expand Down
25 changes: 23 additions & 2 deletions process/process_areas/implementation/guidance/implementation_process_reqs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,21 +15,42 @@
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.

.. 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 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
------------------
Expand Down
5 changes: 3 additions & 2 deletions process/process_areas/verification/verification_workflows.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading