From 8ecf997e52d9d041b7a4cef9fd146a300d6f1bbd Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Wed, 19 Mar 2025 22:00:57 +0000 Subject: [PATCH 1/7] process: Python Coding Guidelines --- .../implementation/guidance/index.rst | 1 + .../guidance/python/coding_guidelines.rst | 89 +++++++++++++++++++ .../implementation/guidance/python/index.rst | 21 +++++ 3 files changed, 111 insertions(+) create mode 100644 docs/process/process_areas/implementation/guidance/python/coding_guidelines.rst create mode 100644 docs/process/process_areas/implementation/guidance/python/index.rst diff --git a/docs/process/process_areas/implementation/guidance/index.rst b/docs/process/process_areas/implementation/guidance/index.rst index 91238440325..529d620fb7b 100644 --- a/docs/process/process_areas/implementation/guidance/index.rst +++ b/docs/process/process_areas/implementation/guidance/index.rst @@ -20,6 +20,7 @@ Guidance implementation_guideline cpp/index + python/index implementation_checklist detailed_design_template implementation_process_reqs diff --git a/docs/process/process_areas/implementation/guidance/python/coding_guidelines.rst b/docs/process/process_areas/implementation/guidance/python/coding_guidelines.rst new file mode 100644 index 00000000000..be588da2a5c --- /dev/null +++ b/docs/process/process_areas/implementation/guidance/python/coding_guidelines.rst @@ -0,0 +1,89 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Writing Python Code +################### + +.. gd_guidl:: Coding Guidelines Python + :id: gd_guidl__python_coding_guidelines + :status: valid + +Coding Guidelines +================= +.. warning:: Python is not meant to be used directly in safety critical systems. The following guidelines are only meant for tooling. + Every tool written will need to be evaluated for safety criticallity (TCL). + + +**Consistency within score matters more than personal preference**. + +The art lies in balancing completeness of this document vs keeping it short, since frankly, no one +will read a long document. Let's focus on issues that actively come up in real life and are worth +discussing and agreeing upon, not on things that *might* be important. (We don't want to write a +book here. And we don't have to, since Python is not used for safety critical systems.) + +This guide is a **living document**—keep it concise, relevant, and practical. + +We assume basic programming and software-engineering know-how and will not repeat basics here! Go +ask Google or ChatGPT. Or one of these established Python best practice websites: + +- [PEP 8](https://pep8.org/) +- [The Hitchhiker's Guide to Python](https://docs.python-guide.org/) +- [Real Python](https://realpython.com/) + +Comments +-------- +- The first rule of comments is to write them **only when something is worth explaining**. +- Comments should explain *why* the code does something, not *what* it does. +- Avoid redundant comments: if the code is clear enough, a comment is not needed. + +Testing +------- +- **Readability:** For some reason, people tend to forget all they have ever learned about + readability when writing tests. **Tests do not have tests.** They must be even more readable than + production code! +- **Mocking is an anti-pattern.** Well... it's complex. We don't want to write a book on mocking + here. Just really, really consider whether mocking is the best approach. - Favor dependency + injection and lightweight fixtures over excessive mocking. Mocks should not replace proper + design. +- **Do not test every single function or class!** Instead: - Focus on testing *behavior*, not + implementation details. Overly fine-grained tests lead to brittle code and high maintenance. +- **Boundary conditions:** - Edge cases often break things. Think about invalid input, large data + sets, empty cases, and concurrency issues. + +Documentation +-------------------- +- If your documentation doesn't fit into a comment, create a `README.md` in the directory of the + tool. +- `README.md` should explain the overall architecture and key design decisions. +- If the design impacts multiple components, consider an architecture diagram. +- User-facing documentation is stored under `docs/guidance`. + + +Tools & Versions +================ + +We're using Python, Ruff (linting & formatting), Pyright (linting) and pytest for our tooling. The +versions are managed by the infrastructure community and will be updated as frequently as possible. +The configuration is managed by infrastructure and process communities. + +*Compliance to all tools is mandatory.* + +Currently we do NOT aim at supporting older Python versions. + +Templates, Checklists and other guidelines +------------------------------------------------ + +While the S-CORE templates and checklists are far from useless, and should be adhered to in +general, they are not necessary for Python Code. The same goes for the ISO26262 guidelines: while +they are important and should be followed in general, they are not applicable to Python Code. diff --git a/docs/process/process_areas/implementation/guidance/python/index.rst b/docs/process/process_areas/implementation/guidance/python/index.rst new file mode 100644 index 00000000000..6c521fe1dbf --- /dev/null +++ b/docs/process/process_areas/implementation/guidance/python/index.rst @@ -0,0 +1,21 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Python +###### + +.. toctree:: + :maxdepth: 1 + + coding_guidelines From 117badd9e524a5ef5685838327450cd1f821a082 Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Mon, 24 Mar 2025 13:23:24 +0000 Subject: [PATCH 2/7] move guidelines to contribute --- .../development}/cpp/code_analysis.rst | 7 ++----- .../development}/cpp/coding_guidelines.rst | 5 ++--- .../guidance => contribute/development}/cpp/index.rst | 0 .../development}/cpp/misra_2023_rule_mapping.rst | 5 ++--- docs/contribute/development/index.rst | 3 ++- .../development}/python/coding_guidelines.rst | 11 ++--------- .../development}/python/index.rst | 0 .../process_areas/implementation/guidance/index.rst | 2 -- 8 files changed, 10 insertions(+), 23 deletions(-) rename docs/{process/process_areas/implementation/guidance => contribute/development}/cpp/code_analysis.rst (94%) rename docs/{process/process_areas/implementation/guidance => contribute/development}/cpp/coding_guidelines.rst (96%) rename docs/{process/process_areas/implementation/guidance => contribute/development}/cpp/index.rst (100%) rename docs/{process/process_areas/implementation/guidance => contribute/development}/cpp/misra_2023_rule_mapping.rst (79%) rename docs/{process/process_areas/implementation/guidance => contribute/development}/python/coding_guidelines.rst (88%) rename docs/{process/process_areas/implementation/guidance => contribute/development}/python/index.rst (100%) diff --git a/docs/process/process_areas/implementation/guidance/cpp/code_analysis.rst b/docs/contribute/development/cpp/code_analysis.rst similarity index 94% rename from docs/process/process_areas/implementation/guidance/cpp/code_analysis.rst rename to docs/contribute/development/cpp/code_analysis.rst index 9e2c37be58a..bde6f78eba3 100644 --- a/docs/process/process_areas/implementation/guidance/cpp/code_analysis.rst +++ b/docs/contribute/development/cpp/code_analysis.rst @@ -15,12 +15,9 @@ Code Analysis C++ ################# -.. gd_guidl:: Static Code Analysis - :id: gd_guidl__cpp__code_analysis +.. document:: Static Code Analysis C++ + :id: doc__cpp__code_analysis :status: valid - :complies: std_req__iso26262__software_1, std_req__iso26262__software_2, std_req__iso26262__software_3, std_req__iso26262__software_31 - - Guideline for Static Code Analysis Static Code Analysis ==================== diff --git a/docs/process/process_areas/implementation/guidance/cpp/coding_guidelines.rst b/docs/contribute/development/cpp/coding_guidelines.rst similarity index 96% rename from docs/process/process_areas/implementation/guidance/cpp/coding_guidelines.rst rename to docs/contribute/development/cpp/coding_guidelines.rst index 85482c5ded2..feff356c497 100644 --- a/docs/process/process_areas/implementation/guidance/cpp/coding_guidelines.rst +++ b/docs/contribute/development/cpp/coding_guidelines.rst @@ -15,10 +15,9 @@ Writing C++ Code ################ -.. gd_guidl:: Coding Guidelines CPP - :id: gd_guidl__cpp_coding_guidelines +.. document:: Coding Guidelines C++ + :id: doc__cpp_coding_guidelines :status: valid - :complies: std_req__iso26262__software_1, std_req__iso26262__software_2, std_req__iso26262__software_3 Coding Guidelines ================= diff --git a/docs/process/process_areas/implementation/guidance/cpp/index.rst b/docs/contribute/development/cpp/index.rst similarity index 100% rename from docs/process/process_areas/implementation/guidance/cpp/index.rst rename to docs/contribute/development/cpp/index.rst diff --git a/docs/process/process_areas/implementation/guidance/cpp/misra_2023_rule_mapping.rst b/docs/contribute/development/cpp/misra_2023_rule_mapping.rst similarity index 79% rename from docs/process/process_areas/implementation/guidance/cpp/misra_2023_rule_mapping.rst rename to docs/contribute/development/cpp/misra_2023_rule_mapping.rst index 4128ad1fa35..6f3757d5367 100644 --- a/docs/process/process_areas/implementation/guidance/cpp/misra_2023_rule_mapping.rst +++ b/docs/contribute/development/cpp/misra_2023_rule_mapping.rst @@ -15,10 +15,9 @@ MISRA C++:2023 Rule Mapping ########################### -.. gd_guidl:: MISRA C++:2023 Rule Mapping - :id: gd_guidl__cpp__misra2023_rule_mapping +.. document:: MISRA C++:2023 Rule Mapping + :id: doc__cpp__misra2023_rule_mapping :status: draft - :complies: std_req__iso26262__software_1, std_req__iso26262__software_2, std_req__iso26262__software_3, std_req__iso26262__software_31 .. .. csv-table:: MISRA C++:2023 Rule Mapping diff --git a/docs/contribute/development/index.rst b/docs/contribute/development/index.rst index 139908d47cb..faff70c4e1b 100644 --- a/docs/contribute/development/index.rst +++ b/docs/contribute/development/index.rst @@ -19,4 +19,5 @@ Development :maxdepth: 1 development_environment - + cpp/index + python/index diff --git a/docs/process/process_areas/implementation/guidance/python/coding_guidelines.rst b/docs/contribute/development/python/coding_guidelines.rst similarity index 88% rename from docs/process/process_areas/implementation/guidance/python/coding_guidelines.rst rename to docs/contribute/development/python/coding_guidelines.rst index be588da2a5c..f25c00d4eef 100644 --- a/docs/process/process_areas/implementation/guidance/python/coding_guidelines.rst +++ b/docs/contribute/development/python/coding_guidelines.rst @@ -15,8 +15,8 @@ Writing Python Code ################### -.. gd_guidl:: Coding Guidelines Python - :id: gd_guidl__python_coding_guidelines +.. document:: Coding Guidelines Python + :id: doc__python_coding_guidelines :status: valid Coding Guidelines @@ -80,10 +80,3 @@ The configuration is managed by infrastructure and process communities. *Compliance to all tools is mandatory.* Currently we do NOT aim at supporting older Python versions. - -Templates, Checklists and other guidelines ------------------------------------------------- - -While the S-CORE templates and checklists are far from useless, and should be adhered to in -general, they are not necessary for Python Code. The same goes for the ISO26262 guidelines: while -they are important and should be followed in general, they are not applicable to Python Code. diff --git a/docs/process/process_areas/implementation/guidance/python/index.rst b/docs/contribute/development/python/index.rst similarity index 100% rename from docs/process/process_areas/implementation/guidance/python/index.rst rename to docs/contribute/development/python/index.rst diff --git a/docs/process/process_areas/implementation/guidance/index.rst b/docs/process/process_areas/implementation/guidance/index.rst index 529d620fb7b..145d1ca0770 100644 --- a/docs/process/process_areas/implementation/guidance/index.rst +++ b/docs/process/process_areas/implementation/guidance/index.rst @@ -19,8 +19,6 @@ Guidance :maxdepth: 1 implementation_guideline - cpp/index - python/index implementation_checklist detailed_design_template implementation_process_reqs From 689e0cd43eaa209126dbc7fa4e343146f2d05fd8 Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Mon, 24 Mar 2025 13:31:28 +0000 Subject: [PATCH 3/7] Coding Guidelines are docs and not guidelines --- docs/contribute/development/cpp/code_analysis.rst | 4 ++-- docs/platform_management_plan/software_development.rst | 2 +- .../implementation/guidance/implementation_guideline.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contribute/development/cpp/code_analysis.rst b/docs/contribute/development/cpp/code_analysis.rst index bde6f78eba3..87ae559700a 100644 --- a/docs/contribute/development/cpp/code_analysis.rst +++ b/docs/contribute/development/cpp/code_analysis.rst @@ -21,9 +21,9 @@ Code Analysis C++ Static Code Analysis ==================== -In order to fulfil the SCORE related standard requirements a concept for *Static Code Analysis* needs to be established. Input for the analysis is based upon *MISRA* and *ISO26262* standards in accordance to the :need:`gd_guidl__cpp_coding_guidelines`. +In order to fulfil the SCORE related standard requirements a concept for *Static Code Analysis* needs to be established. Input for the analysis is based upon *MISRA* and *ISO26262* standards in accordance to the :need:`doc__cpp_coding_guidelines`. -Checking those rules can partially be automated and implemented by a combination of different tools. Thus a mapping needs to be established which provides a linkage of all *MISRA* requirements to the respective tool requirements/rules. For *MISRA C++:2023* this mapping is established: :need:`here ` +Checking those rules can partially be automated and implemented by a combination of different tools. Thus a mapping needs to be established which provides a linkage of all *MISRA* requirements to the respective tool requirements/rules. For *MISRA C++:2023* this mapping is established: :need:`here ` .. needuml:: diff --git a/docs/platform_management_plan/software_development.rst b/docs/platform_management_plan/software_development.rst index f2b3e654e1f..0ec671f44dd 100644 --- a/docs/platform_management_plan/software_development.rst +++ b/docs/platform_management_plan/software_development.rst @@ -69,7 +69,7 @@ The design guideline is defined in :need:`doc_concept__imp__concept` and :need:` Coding guideline ^^^^^^^^^^^^^^^^ -**C++** - see :need:`gd_guidl__cpp_coding_guidelines` +**C++** - see :need:`doc__cpp_coding_guidelines` **Rust** - state of the art open source Rust guidelines are currently developed by `Safety Critical Rust Consortium `_ (which will be adopted by the S-CORE project) diff --git a/docs/process/process_areas/implementation/guidance/implementation_guideline.rst b/docs/process/process_areas/implementation/guidance/implementation_guideline.rst index 0ce5472c692..758d33565aa 100644 --- a/docs/process/process_areas/implementation/guidance/implementation_guideline.rst +++ b/docs/process/process_areas/implementation/guidance/implementation_guideline.rst @@ -33,7 +33,7 @@ Detailed description which steps are need for implementation. 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. -#. Implement the source code, by using the coding guidelines :need:`gd_guidl__cpp_coding_guidelines` for C++, +#. Implement the source code, by using the coding guidelines :need:`doc__cpp_coding_guidelines` for C++, or for Rust. #. 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. From 101cbfe41911befe03367c3ff2901415ae6f5942 Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Mon, 24 Mar 2025 13:32:21 +0000 Subject: [PATCH 4/7] fix whitespace --- docs/contribute/development/cpp/code_analysis.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/development/cpp/code_analysis.rst b/docs/contribute/development/cpp/code_analysis.rst index 87ae559700a..369d3e5272e 100644 --- a/docs/contribute/development/cpp/code_analysis.rst +++ b/docs/contribute/development/cpp/code_analysis.rst @@ -23,7 +23,7 @@ Static Code Analysis ==================== In order to fulfil the SCORE related standard requirements a concept for *Static Code Analysis* needs to be established. Input for the analysis is based upon *MISRA* and *ISO26262* standards in accordance to the :need:`doc__cpp_coding_guidelines`. -Checking those rules can partially be automated and implemented by a combination of different tools. Thus a mapping needs to be established which provides a linkage of all *MISRA* requirements to the respective tool requirements/rules. For *MISRA C++:2023* this mapping is established: :need:`here ` +Checking those rules can partially be automated and implemented by a combination of different tools. Thus a mapping needs to be established which provides a linkage of all *MISRA* requirements to the respective tool requirements/rules. For *MISRA C++:2023* this mapping is established: :need:`here ` .. needuml:: From 77d6dec1f7245b51f066dd52ac3fe540a13cf848 Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Fri, 28 Mar 2025 08:59:22 +0100 Subject: [PATCH 5/7] fix 3 review hints --- .../development/python/coding_guidelines.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/contribute/development/python/coding_guidelines.rst b/docs/contribute/development/python/coding_guidelines.rst index f25c00d4eef..834f87e682b 100644 --- a/docs/contribute/development/python/coding_guidelines.rst +++ b/docs/contribute/development/python/coding_guidelines.rst @@ -29,8 +29,11 @@ Coding Guidelines The art lies in balancing completeness of this document vs keeping it short, since frankly, no one will read a long document. Let's focus on issues that actively come up in real life and are worth -discussing and agreeing upon, not on things that *might* be important. (We don't want to write a -book here. And we don't have to, since Python is not used for safety critical systems.) +discussing and agreeing upon, not on things that *might* be important. + +We don't want to write a book here. And we don't have to, since Python is not used for safety +critical systems. However, to provide sufficient argumentation for code quality when it comes to +tool qualification it is necessary to have and actively use guidelines. This guide is a **living document**—keep it concise, relevant, and practical. @@ -46,6 +49,7 @@ Comments - The first rule of comments is to write them **only when something is worth explaining**. - Comments should explain *why* the code does something, not *what* it does. - Avoid redundant comments: if the code is clear enough, a comment is not needed. +- Take the user's perspective when writing docstrings Testing ------- @@ -77,6 +81,6 @@ We're using Python, Ruff (linting & formatting), Pyright (linting) and pytest fo versions are managed by the infrastructure community and will be updated as frequently as possible. The configuration is managed by infrastructure and process communities. -*Compliance to all tools is mandatory.* +*Compliance to all tools is mandatory, and will be enforced by pull request checks.* Currently we do NOT aim at supporting older Python versions. From 59c8beffaf81c90840c609d7995671fa5b3a6349 Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Fri, 28 Mar 2025 09:02:55 +0100 Subject: [PATCH 6/7] add rust placeholder --- docs/contribute/development/index.rst | 1 + .../development/rust/coding_guidelines.rst | 22 +++++++++++++++++++ docs/contribute/development/rust/index.rst | 21 ++++++++++++++++++ 3 files changed, 44 insertions(+) create mode 100644 docs/contribute/development/rust/coding_guidelines.rst create mode 100644 docs/contribute/development/rust/index.rst diff --git a/docs/contribute/development/index.rst b/docs/contribute/development/index.rst index faff70c4e1b..086e6be44b1 100644 --- a/docs/contribute/development/index.rst +++ b/docs/contribute/development/index.rst @@ -20,4 +20,5 @@ Development development_environment cpp/index + rust/index python/index diff --git a/docs/contribute/development/rust/coding_guidelines.rst b/docs/contribute/development/rust/coding_guidelines.rst new file mode 100644 index 00000000000..1ce642536be --- /dev/null +++ b/docs/contribute/development/rust/coding_guidelines.rst @@ -0,0 +1,22 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Writing Rust Code +################# + +.. document:: Coding Guidelines Rust + :id: doc__rust_coding_guidelines + :status: invalid + +.. note:: The Rust coding guidelines are not yet defined. This is a placeholder for future content. diff --git a/docs/contribute/development/rust/index.rst b/docs/contribute/development/rust/index.rst new file mode 100644 index 00000000000..b0fb6a40edf --- /dev/null +++ b/docs/contribute/development/rust/index.rst @@ -0,0 +1,21 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Rust +#### + +.. toctree:: + :maxdepth: 1 + + coding_guidelines From 565ea1fb8d5116bcd3aa13ffef0db041c228381a Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Mon, 31 Mar 2025 11:33:47 +0200 Subject: [PATCH 7/7] fix merge problem --- docs/contribute/development/cpp/code_analysis.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/development/cpp/code_analysis.rst b/docs/contribute/development/cpp/code_analysis.rst index 4dd9574c624..abb4e4ee584 100644 --- a/docs/contribute/development/cpp/code_analysis.rst +++ b/docs/contribute/development/cpp/code_analysis.rst @@ -23,7 +23,7 @@ Code Analysis C++ Static Code Analysis ==================== -In order to fulfil the S-CORE related standard requirements a concept for *Static Code Analysis* needs to be established. Input for the analysis is based upon *MISRA* and *ISO26262* standards in accordance to the :need:`gd_guidl__cpp_coding_guidelines`. +In order to fulfil the S-CORE related standard requirements a concept for *Static Code Analysis* needs to be established. Input for the analysis is based upon *MISRA* and *ISO26262* standards in accordance to the :need:`doc__cpp_coding_guidelines`. Checking those rules can partially be automated and implemented by a combination of different tools. Thus a mapping needs to be established which provides a linkage of all *MISRA* requirements to the respective tool requirements/rules. For *MISRA C++:2023* this mapping is established: :need:`here `