diff --git a/process/process_areas/implementation/guidance/_assets/static_view.drawio.svg b/process/process_areas/implementation/guidance/_assets/static_view.drawio.svg index 34c3c8ed7a..bc97dcd54a 100644 --- a/process/process_areas/implementation/guidance/_assets/static_view.drawio.svg +++ b/process/process_areas/implementation/guidance/_assets/static_view.drawio.svg @@ -1,4 +1,4 @@ - + @@ -21,13 +21,13 @@
- Static Diagram + Folder structure and Static Diagram
- Static Diagram + Folder structure and Static Diagram diff --git a/process/process_areas/implementation/guidance/implementation_guideline.rst b/process/process_areas/implementation/guidance/implementation_guideline.rst index c81b98325d..21750d717c 100644 --- a/process/process_areas/implementation/guidance/implementation_guideline.rst +++ b/process/process_areas/implementation/guidance/implementation_guideline.rst @@ -22,12 +22,21 @@ Guideline :complies: std_req__iso26262__software_744[version==1], std_req__iso26262__software_841[version==1], std_req__iso26262__software_842[version==1], + 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], + std_req__aspice_40__SWE-3-BP2[version==1], + std_req__aspice_40__SWE-3-BP3[version==1], + std_req__aspice_40__SWE-3-BP4[version==1], std_req__aspice_40__iic-11-05[version==1] This document describes the general guidance for implementation based on the concept which is defined :need:`[[title]]`. An example of a Detailed Design is maintained in the `module template documentation `_. +**Scope:** This guideline applies to both QM (Quality Management) and ASIL B components. Where specific requirements differ between QM and ASIL B (e.g., complexity thresholds, design principles), they are explicitly noted. + Workflow for Implementation =========================== @@ -36,12 +45,13 @@ 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. + 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. #. 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. +#. 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. #. Check the results of the static and dynamic code analysis (this includes compiler warnings). Acceptance criteria are defined in the Verification Plan :need:`gd_temp__verification_plan`. #. Fix or justify the errors. #. Merge the pull request. @@ -54,6 +64,12 @@ 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. +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 +the units that implement those requirements. This creates the necessary requirement-to-unit link for compliance +and audit purposes. See the :ref:`verification process area ` for details on how requirements +are verified through tests that exercise specific units. + .. figure:: _assets/static_view.drawio.svg :align: center :width: 30% @@ -75,3 +91,140 @@ The dynamic diagram satisfies the architecture and implements the requirements o :name: dd_traceability_fig The unit description will be generated automatically based on the comments in the source code and from the interface description. + +Detailed Design Guidance +======================== + +Definition of a Unit +-------------------- + +A **unit** is a **granular, independent entity** of a component that can be **tested separately** +during the unit testing phase. Each unit represents a **self-contained functionality** and is +derived from the decomposition of a component. + +**Characteristics of a Unit** + +- **Independent** - Can be tested in isolation. +- **Granular** - Represents a small, well-defined part of the system. +- **Relational** - Has associations with other units, defined using **UML 2.0 notations** such as + aggregation, composition, and generalization. + +**Examples:** +The definition of a unit depends on the used programming language. Examples for a unit are +a source file, a definition file (e.g. c++ header), classes, structs, and functions. +This list is not complete or exclusive. + +**Units in UML Diagrams** + +- **C++ development** - Each **class** can be considered a **unit** in the design. +- **Rust development** - A **unit** is modeled using a **combination of ``struct`` and ``trait``**, + as Rust does not have traditional classes. + +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. + +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. + +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 +and descriptions should not be outdated, should stay consistent with the source code, and should not +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 (e.g. MISRA C for C/C++, Clippy lints for Rust) as specified in the software development plan. + +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, including requirements for limited complexity (one-entry-one-exit, +no recursion, no unconditional jumps), restricted use of pointers, limited global variables, and absence +of hidden data/control flow. These principles shall be enforced through coding guidelines and automated +static analysis tooling. + +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. +These comments, along with commit messages, and any additional documentation accompanying the +source code should 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 +of the component, they should follow the same documentation rules as the component interfaces +(see :need:`gd_guidl__arch_design`). + +Especially for public interfaces, the interface naming should follow the naming of the logical +interface in the feature and component architecture to ensure traceability. The interface +documentation should be clear and comprehensive so users of the unit can understand how to interact +with it without needing to read implementation details. The documentation should be maintained and +updated as the implementation evolves. + +Diagrams +-------- + +Developers may add **class diagrams** or **sequence diagrams** at the unit level if they believe +it helps to explain the source code better. These are optional and serve as supplementary +documentation. + +Static View +``````````` + +If a static view is used, it should provide an overview of the **units** and their relationships +using **UML 2.0 notations**, such as **aggregation, composition, and generalization**. It is depicted +through **UML structural diagrams**, including: + +- **Class Diagrams** - Define classes, attributes, methods, and relationships (e.g. inheritance, + associations, dependencies). +- **Component Diagrams** - Show the organization and dependencies among software units, which can be + used to represent the units within a component. +- **Rust** - Uses ``struct`` and ``trait`` combinations to represent units in UML diagrams. + +The static view need not cover every class or struct in the implementation - it should show the units +and relationships that are necessary to understand the detailed design. + +The naming of the units and their interfaces in the static view should match the naming in the source +code to ensure traceability. Implementation details that are not relevant at the design level may be +omitted. + +According to the software development plan of the project, the developer may use tools like PlantUML +or Draw.io for such diagrams. + +Dynamic View +```````````` + +An optional **dynamic view** illustrates how the **units** within a component interact over their +**interfaces** to fulfill a specific **use case** or **functionality**. This is a **component-level** +view - individual per-unit dynamic diagrams are **not required**. + +It is represented using **UML behavioural diagrams**, including: + +- **Sequence Diagrams** - Depict interactions between objects in a time-ordered sequence, + highlighting how methods are invoked and how control flows between objects over time. +- **State Machine Diagrams** - Show how the state of an object changes in response to events, + allowing the modeling of complex state transitions (if there is stateful behaviour). + +A dynamic view is optional when the component's behaviour is straightforward and can be understood +from the static view and interface documentation alone (similar to the rules depicted in +:need:`gd_guidl__arch_design`). + +Example using PlantUML: + +.. uml:: + + @startuml + participant UnitA + participant UnitB + + UnitA -> UnitB : request() + UnitB --> UnitA : response() + @enduml diff --git a/process/process_areas/implementation/guidance/implementation_process_reqs.rst b/process/process_areas/implementation/guidance/implementation_process_reqs.rst index 007ef2ea50..49acf6eaf2 100644 --- a/process/process_areas/implementation/guidance/implementation_process_reqs.rst +++ b/process/process_areas/implementation/guidance/implementation_process_reqs.rst @@ -15,6 +15,9 @@ Process Requirements #################### +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 @@ -26,13 +29,13 @@ Process Requirements 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. + The static diagram shall represent the units and their relationships using UML notations. Diagram Attributes ------------------ -.. gd_req:: Diagram attribute: UID - :id: gd_req__impl_diagram_uid +.. gd_req:: Diagram attribute: unique name + :id: gd_req__impl_diagram_name :status: valid :version: 1 :tags: manual_prio_1, attribute, mandatory @@ -42,11 +45,11 @@ Diagram Attributes std_req__iso26262__software_845[version==1], std_req__aspice_40__SWE-3-BP2[version==1] - Each diagram shall have a unique ID. It shall consist of three parts: + Each diagram shall have a unique name (realized by it's file name). It shall consist of three parts: - * type of diagram - * structural element - * keyword describing the content of the diagram + * type of diagram + * structural element + * keyword describing the content of the diagram Consider the project's naming convention. @@ -66,44 +69,6 @@ Diagram Attributes This means for example that the word "shall" is not allowed in the title for all diagram. -.. gd_req:: Diagram attribute: security - :id: gd_req__impl_diagram_security - :status: valid - :version: 1 - :tags: manual_prio_2, attribute, mandatory - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall have a security relevance identifier: - - * Yes - * No - -.. gd_req:: Diagram attribute: safety - :id: gd_req__impl_diagram_safety - :status: valid - :version: 1 - :tags: manual_prio_1, attribute, mandatory - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall have a automotive safety integrity level (ASIL) identifier: - - * QM - * ASIL_B - -.. gd_req:: Diagram attribute: status - :id: gd_req__impl_diagram_status - :status: valid - :version: 1 - :tags: manual_prio_1, attribute, mandatory - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall have a status: - - * valid - * invalid - .. gd_req:: Diagram attribute: description :id: gd_req__impl_diagram_description :status: valid @@ -112,241 +77,87 @@ Diagram Attributes :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] :satisfies: wf__sw_detailed_design[version==1] - Each diagram shall have a description. The description shall provide a needarch or image of the diagram. + Each diagram shall have a description. .. _detailed_design_linkage: -Diagram Linkage -''''''''''''''' - -.. gd_req:: Diagram Linkage check Component Requirement - :id: gd_req__impl_diagram_check_req - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1], std_req__aspice_40__iic-13-51[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall be linked to the corresponding component requirement via the attribute implements. - -.. gd_req:: Diagram Linkage Component Requirement - :id: gd_req__impl_diagram_linkage_req - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall be automatically linked (inverse direction) to the corresponding component requirement via the "implemented by" linkage. - -.. gd_req:: Diagram Linkage check Component Architecture - :id: gd_req__impl_diagram_check_arch - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1], std_req__aspice_40__iic-13-51[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall be linked to the corresponding component architecture via the attribute satisfies. - -.. gd_req:: Diagram Linkage Component Architecture - :id: gd_req__impl_diagram_linkage_arch - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall be automatically linked (inverse direction) to the corresponding component architecture via the "satisfied by" linkage. - -.. gd_req:: Diagram Linkage check Component ID - :id: gd_req__impl_diagram_check_id - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall be linked to the corresponding component id via the attribute belongs_to. - -.. gd_req:: Diagram Linkage Component ID - :id: gd_req__impl_diagram_linkage_id - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall be automatically linked (inverse direction) to the corresponding component id via the "belongs by" linkage. - -.. gd_req:: Diagram Linkage includes - :id: gd_req__impl_diagram_check_includes - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall be linked to the corresponding - - SW Unit - - SW Unit Interface - via the attribute includes. - -.. gd_req:: Diagram Linkage includes - :id: gd_req__impl_diagram_linkage_includes - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each diagram shall be automatically linked (inverse direction) to the corresponding - - SW Unit - - SW Unit Interface - via the "included by" linkage. - Diagram Checks '''''''''''''' -.. gd_req:: Diagram mandatory attributes provided - :id: gd_req__impl_diagram_mandatory +.. gd_req:: Diagram mandatory consistency + :id: gd_req__impl_diagram_consistency :status: valid - :version: 1 - :tags: prio_2_automation, attribute, check + :version: 2 + :tags: prio_3_automation, attribute, check :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] :satisfies: wf__sw_detailed_design[version==1] - It shall be checked if all mandatory attributes for each diagram are provided by the user. For all diagrams following attributes shall be mandatory: - - .. needtable:: Overview mandatory Diagram attributes - :filter: "mandatory" in tags and "attribute" in tags and "implementation" in tags and type == "gd_req" - :style: table - :columns: title - :colwidths: 30 + It shall be checked if all diagrams are consistent with the source code and the design principles + outlined in the development plan. This includes checking 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. + That means the diagrams and descriptions should not be outdated and be consistent with + the source code and not introduce new terminology or concepts that are not present in the code. Unit Attributes --------------- -.. gd_req:: Unit attribute: UID - :id: gd_req__impl_unit_uid +.. gd_req:: Unit naming + :id: gd_req__impl_unit_naming :status: valid :version: 1 :tags: manual_prio_1, attribute, mandatory :satisfies: wf__sw_detailed_design[version==1] :complies: std_req__iso26262__software_843[version==1], std_req__aspice_40__SWE-3-BP1[version==1] - Each unit shall have a unique ID. It shall consist of three parts: + Each unit shall have a proper naming, which is unique within the component and + follows a consistent naming convention. The name should be descriptive and reflect + the functionality of the unit to ensure traceability and understandability. - * type of unit - * structural element - * keyword describing the content of the unit + The naming convention should be defined in the project guidelines and consistently applied across all units. - Consider the project's naming convention. - -.. gd_req:: Unit attribute: description +.. gd_req:: Unit description :id: gd_req__impl_unit_description :status: valid :version: 1 - :tags: manual_prio_1, attribute, mandatory - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each unit shall have a description. - -Unit Linkage -'''''''''''' - -.. gd_req:: Unit Linkage check Component ID - :id: gd_req__impl_unit_check_id - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each unit shall be linked to the corresponding component id via the attribute belongs_to. - -.. gd_req:: Unit Linkage Component ID - :id: gd_req__impl_unit_linkage_id - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated + :tags: manual_prio_1, mandatory :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] :satisfies: wf__sw_detailed_design[version==1] - Each unit shall be automatically linked (inverse direction) to the corresponding component id via the "belongs by" linkage. + Each unit shall have a description in the source code. Interface Attributes -------------------- -.. gd_req:: Interface attribute: UID - :id: gd_req__impl_interface_uid +.. gd_req:: Interface naming + :id: gd_req__impl_interface_naming :status: valid :version: 1 - :tags: manual_prio_1, attribute, mandatory + :tags: manual_prio_1, mandatory :satisfies: wf__sw_detailed_design[version==1] :complies: std_req__iso26262__software_843[version==1], std_req__aspice_40__SWE-3-BP1[version==1] - Each interface shall have a unique ID. It shall consist of three parts: - - * type of interface - * structural element - * keyword describing the content of the interface + Each interface shall have a proper naming, which is unique within the component and + follows a consistent naming convention. The name should be descriptive and reflect + the functionality of the interface to ensure traceability and understandability. Consider the project's naming convention. -.. gd_req:: Interface attribute: description +.. gd_req:: Interface description :id: gd_req__impl_interface_description :status: valid :version: 1 - :tags: manual_prio_1, attribute, mandatory - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each interface shall have a description. - -Interface Linkage -''''''''''''''''' - -.. gd_req:: Interface Linkage check SW Unit ID - :id: gd_req__impl_interface_check_id - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each interface shall be linked to the corresponding SW Unit id via the attribute belongs_to. - -.. gd_req:: Interface Linkage SW Unit ID - :id: gd_req__impl_interface_linkage_id - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each interface shall be automatically linked (inverse direction) to the corresponding SW Unit id via the "belongs by" linkage. - -.. gd_req:: Interface Linkage check Architecture - :id: gd_req__impl_interface_check_req - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated - :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] - :satisfies: wf__sw_detailed_design[version==1] - - Each interface shall be linked to the corresponding architecture via the attribute implements. - -.. gd_req:: Interface Linkage Architecture - :id: gd_req__impl_interface_linkage_req - :status: valid - :version: 1 - :tags: prio_2_automation, attribute, automated + :tags: manual_prio_1, mandatory :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] :satisfies: wf__sw_detailed_design[version==1] - Each interface shall be automatically linked (inverse direction) to the corresponding architecture via the "implemented by" linkage. + Each interface shall have a description in the source code if the source code does not + already provide sufficient information. It should provide a clear and comprehensive explanation + of the interface's purpose, its inputs and outputs, and how it interacts with other units + or components. The description should be sufficient to allow users of the interface + to understand how to interact with it without needing to read the implementation details. + It should also include any relevant information about the expected behavior, constraints, + and any assumptions made in the design of the interface. The documentation should be + maintained and updated as the implementation evolves to ensure it remains accurate and useful. Dependency Analysis ''''''''''''''''''' @@ -360,7 +171,8 @@ Dependency Analysis :complies: std_req__iso26262__software_942[version==1] For each component a dependency tree view shall be created to support design inspection and Safety Analysis. - It shall show the libraries used by the component (i.e. which libraries are linked to the component, defined as CI build tool target) up to the leaves of the tree. + It shall show the libraries used by the component (i.e. which libraries are linked to the component, + defined as CI build tool target) up to the leaves of the tree. .. needextend:: docname is not None and "process_areas/implementation" in docname :+tags: implementation diff --git a/process/process_areas/implementation/implementation_concept.rst b/process/process_areas/implementation/implementation_concept.rst index 6ccfba0225..f05b42fa7f 100644 --- a/process/process_areas/implementation/implementation_concept.rst +++ b/process/process_areas/implementation/implementation_concept.rst @@ -39,9 +39,10 @@ Detailed Design =============== In this step, the **components** are broken down into smaller, independent **units** that can be -**tested separately** during the unit testing phase. This decomposition shall support the implementation -and testing of the component's requirements while adhering to the design principles and patterns -established in the architecture. +**tested separately** during the unit testing phase. The basis for this decomposition are the +:need:`Component Requirements ` and the :need:`Component Architecture `. +The decomposition shall support the implementation and testing of the component's requirements while +adhering to the design principles and patterns established in the architecture. Following the **Detailed Design Template** :need:`gd_temp__detailed_design`, we must document the **design decisions** and **constraints** that guide the decomposition of the component into multiple @@ -57,114 +58,6 @@ The goal is to ensure that the decomposition supports **reusability**, **maintai The detailed design and implementation should follow an **iterative approach**, allowing for continuous improvements in quality through multiple cycles of refinement. -Definition of a Unit --------------------- - -A **unit** is a **granular, independent entity** of a component that can be **tested separately** -during the unit testing phase. Each unit represents a **self-contained functionality** and is -derived from the decomposition of a component. - -**Characteristics of a Unit** - -- **Independent** – Can be tested in isolation. -- **Granular** – Represents a small, well-defined part of the system. -- **Relational** – Has associations with other units, defined using **UML 2.0 notations** such as - aggregation, composition, and generalization. - -**Examples:** -The definition of a unit depends on the used programming language. Examples for a unit are -a source file, a definition file (e.g. c++ header), classes, structs, and functions. -This list is not complete or exclusive. - -**Units in UML Diagrams** - -- **C++ development** – Each **class** can be considered a **unit** in the design. -- **Rust development** – A **unit** is modeled using a **combination of `struct` and `trait`**, - as Rust does not have traditional classes. - -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 -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 -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. - -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. - -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 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). - -Diagrams --------- - -Developers may add **class diagrams** or **sequence diagrams** at the unit level if they believe -it helps to explain the source code better. These are optional and serve as supplementary -documentation — they are not required by the process. - -Static View -``````````` - -If a static view is used it shall provide an overview of the **units** and their -relationships using **UML 2.0 notations**, such as **aggregation, composition, and -generalization**. It is depicted through **UML structural diagrams**, including: - -- **Class Diagrams** – Define classes, attributes, methods, and relationships (e.g., - inheritance, associations, dependencies). -- **Component Diagrams** – Show the organization and dependencies among software units, - which can be used to represent the units within a component. -- **Rust** – Uses `struct` and `trait` combinations to represent units in UML diagrams. - -The static view need not cover every class or struct in the implementation — it should show -the units and relationships that are necessary to understand the detailed design. -The naming of the units and their interfaces in the static view should match the naming -in the source code to ensure traceability. Implementation details that are not relevant -at the design level may be omitted. - -According to the software development plan of the project the developer may use tools -like PlantUML or DrawIo for such diagrams. - -Dynamic View -```````````` - -An optional **dynamic view** illustrates how the **units** within a component interact over their -**interfaces** to fulfill a specific **use case** or **functionality**. This is a -**component-level** view — individual per-unit dynamic diagrams are **not required**. - -It is represented using **UML behavioural diagrams**, including: - -- **Sequence Diagrams** – Depict the interactions between objects in a time-ordered sequence, - highlighting how methods are invoked and how control flows between objects over time. -- **State Machine Diagrams** – Show how the state of an object changes in response to events, - allowing for the modeling of complex state transitions (if there is stateful behaviour). - -A dynamic view is **optional** when the component's behaviour is straightforward and can be -understood from the static view and interface documentation alone (similar to the rules -depicted in :need:`gd_guidl__arch_design`). - -Example using PlantUML: - -.. uml:: - - @startuml - participant UnitA - participant UnitB - - UnitA -> UnitB : request() - UnitB --> UnitA : response() - @enduml +The implementation concept intentionally stays at a high level. Practical guidance for +unit decomposition, source-code documentation, optional diagrams and naming consistency +for traceability is defined in :need:`Implementation Guideline `. diff --git a/process/process_areas/implementation/implementation_workproducts.rst b/process/process_areas/implementation/implementation_workproducts.rst index 23bfb1b79f..287e56e0c3 100644 --- a/process/process_areas/implementation/implementation_workproducts.rst +++ b/process/process_areas/implementation/implementation_workproducts.rst @@ -26,8 +26,8 @@ Implementation Work Products std_req__aspice_40__iic-04-05[version==1], std_req__aspice_40__iic-11-05[version==1] - Implementation includes source code and detailed design (e.g. in form of comments or linked graphical representations) and SW configuration (e.g. #ifdef) - The "how to" is described in the SW Development Plan guidelines + Implementation includes source code and detailed design (e.g. in form of comments or linked graphical representations) and SW configuration (e.g. #ifdef). + The "how to" is described in the SW Development Plan guidelines. .. workproduct:: Implementation Inspection :id: wp__sw_implementation_inspection @@ -36,7 +36,7 @@ Implementation Work Products :tags: doc_lifecycle_model_2 :complies: std_wp__iso26262__software_952[version==1] - Github review with integrated inspection checklist, only valid Detailed Design and Code get merged + Github review with integrated inspection checklist, only valid Detailed Design and Code get merged. .. workproduct:: Software Development Plan :id: wp__sw_development_plan @@ -45,7 +45,7 @@ Implementation Work Products :tags: doc_lifecycle_model_2 :complies: std_wp__iso26262__software_551[version==1], std_wp__iso26262__software_app_c_58[version==1], std_wp__isosae21434__development_1053[version==1] - Process description of SW development including + Process description of SW development including: - selection of design and programming language - design guideline - coding guideline (e.g. MISRA, can also include style guide or naming convention)