python style guide [obsolete]

[AlexanderLanin]

🚧 moved to rst, see #741 🚧
⚠️ do not edit here ⚠️

Python Style Guide

Intro

The art lies in balancing completeness vs the "important stuff," since frankly, no one will read a long document. Therefore, we constantly have different opinions on whether to include new points or not. For the sake of an "80% solution" and just pure effort reduction... let's keep it short. Let's focus on issues that actively come up in our team and are worth discussing and agreeing upon—not things that might be important.

General

• We assume basic programming know-how and will not repeat basics here.
• Unless otherwise stated, we follow established Python best practices. See:
  • PEP 8
  • The Hitchhiker’s Guide to Python
  • Real Python
• Code consistency within the team matters more than personal preference.

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 & base cases:
  • Edge cases often break things. Think about invalid input, large data sets, empty cases, and concurrency issues.

Design 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—not be a full API reference.
• If the design impacts multiple components, consider an architecture diagram.
• User-facing documentation is stored under docs/guidance.

---

This guide is a living document—keep it concise, relevant, and practical.

[dcalavrezo-qorix]

Naming Rules

I think we should maybe enforce a set of naming conventions, something usual like:

Element	Convention	Example
Variables	snake_case	sensor_reading
Constants	UPPER_CASE	MAX_VOLTAGE
Functions	snake_case	compute_checksum()
Classes	PascalCase	SensorModule
Private Members	_single_leading_underscore	_calculate_offset()
Modules	snake_case.py	sensor_utils.py
Packages	snake_case	safety_checks
Test Functions	test_*	test_sensor_overload()

• No single-letter variable names except for loop counters (i, j, k).
• Avoid generic names like temp, data, value unless context is obvious.
• Explicit Boolean names: Use is_, has_, should_ for clarity (is_sensor_active instead of sensor_status).

Design documentation

• Avoid duplication between docstrings and external documentation.

Testing & Verification

• do at least boundary testing: validate inputs at min/max ranges.
• ensure Modified Condition/Decision Coverage (MC/DC) in safety-critical code ( TBD: how to classify the code as safety critical ?

[MaximilianSoerenPollak]

I don't think it has to be 'all' things, I think stuff like @dcalavrezo-qorix said for example the short table with the names, what is expected.
And then the stuff that we can't easily check with linters or formatters. We can still then point towards the outside things, like 'for anything not explicitly stated here on in the configuration the PIP8 guidelines apply' , or whatever.
That shouldn't result in a lot of 'extra' pages and keep the 'spirit' of only the more important things are explicitly mentioned.

[MaximilianSoerenPollak]

I guess maybe one way to think about it or distinguish it would be.
Write everything
Maybe just take it as a rought guideline, not write everything in the docs that a linter would yell at you for that the formatter can't automatically fix, as well as all things that aren't findable/fixable by the linter or formatter.

That way we would have a clear guideline, and in the 'most' annoying part would be documented.

Linter	Formatter	Write in Docs
finds	fixes	❌
finds	can't fix	✅ (sometimes)
can't find	can't fix	✅

[AlexanderLanin]

Should we refer to https://docs.python-guide.org/ or to https://google.github.io/styleguide/pyguide.html or to individual PEPs?

Both links found by @MaximilianSoerenPollak some days/weeks ago

[MaximilianSoerenPollak]

I mean PIP8 is the 'defacto' style guide from python itself. The Google guide goes much further than PIP8, instead of just how to do something, it specifies why and when to do it, e.g. give aliases or etc.

I think linking to PIP8, or maybe the human readable form of it https://pep8.org/ makes sense. We can also link to the other two in case we find specific rules that we might want to adapt from them I think it will be helpful to have those links.

[AlexanderLanin]

Updated. Doesn't fit onto one screen anymore, but it looks good :D