Add embedded by patrickelectric · Pull Request #12 · bluerobotics/software-guidelines

patrickelectric · 2026-01-28T00:20:09Z

No description provided.

Signed-off-by: Patrick José Pereira <patrickelectric@gmail.com>

joaomariolago · 2026-01-28T00:47:18Z

+
+- Follow the project code style and keep it consistent within each file.
+- Prefer small, focused functions over long procedural blocks.
+- Prefer compile-time checksm add run-time checks for safety-critical paths.


Suggested change

- Prefer compile-time checksm add run-time checks for safety-critical paths.

- Prefer compile-time checks, and add run-time checks only for safety-critical paths.

joaomariolago · 2026-01-28T00:48:12Z

+## Preprocessor rules
+
+- Only use `#pragma once` and `#include`
+- Do not use `#define` for inline macros or constants, use `inline`, `const`, `constexpr`, or `consteval` instead.


This assumes that C++ only code is being used, do we want to broad this for maybe Rust/C?

joaomariolago · 2026-01-28T00:50:23Z

+- No spaces around `.` or `->`, and no spaces around unary operators.
+- Naming rules follow the project standard. If none is defined, use:
+  - `lower_snake_case` for functions and variables
+  - `UpperCamel_Case` for classes, structs, enums, and typedefs (e.g., `AP_Compass`)


This is not a valid UpperCamelCase (PascalCase); it is a mixture of naming conventions.
Unless dictated by a specific project style, we should avoid this and try to maintain a single, consistent naming convention.
Mixing conventions or having different rules tends to reduce readability and maintainability, as seen in APIs such as OpenGL.

joaomariolago · 2026-01-28T00:51:11Z

+  - `UpperCamel_Case` for classes, structs, enums, and typedefs (e.g., `AP_Compass`)
+  - lowercase constants and enumerators
+  - uppercase acronyms inside identifiers (e.g., `GCS_MAVLink`)
+  - use underscore for private properties


This is against AV Rule 47

Do we expect to use lots of libraries in our embedded code?
I suspect the compiler would catch any name collisions caused by this, and it seems potentially valuable to indicate throughout the code when something is private 🤷‍♂️

joaomariolago · 2026-01-28T00:52:57Z

+## Class design
+
+- Use `struct` for plain data, `class` for invariants and encapsulation.
+- Keep data members private, avoid public/protected data in classes.


Most of C++ references tends to use member variables/functions to address properties and methods.

Suggested change

- Keep data members private, avoid public/protected data in classes.

- Keep **member variables** private; avoid use of public or protected **member variables** in C++ classes.

joaomariolago · 2026-01-28T01:03:35Z

+## Header and implementation structure
+
+- `.h` for headers, `.cpp` for implementations.
+- Headers contain declarations only, no non-const data or function definitions.


Suggested change

- Headers contain declarations only, no non-const data or function definitions.

- Headers should contain declarations only; by default, they must not contain non-const data or function definitions, except for:

- inline functions

- templates

- `constexpr` or `consteval` definitions

joaomariolago · 2026-01-28T01:05:12Z

+
+- `.h` for headers, `.cpp` for implementations.
+- Headers contain declarations only, no non-const data or function definitions.
+  - Exceptions: inline functions and templates.


Suggested change

- Exceptions: inline functions and templates.

Join this with suggestion above

joaomariolago · 2026-01-28T01:13:33Z

+  unless the platform and toolchain explicitly support it and memory costs are measured.
+- Prefer fixed-size arrays, if dynamic containers are needed, use project-approved
+  alternatives.
+- Avoid bit fields, use plain booleans.


Accordingly to JSF AV Rules [154, 155, 156]

Suggested change

- Avoid bit fields, use plain booleans.

- Avoid using bit-fields for data packing or space optimization.

- For general state and control logic, prefer plain boolean or integer members over bit-fields.

- Bit-fields may be used only when required for hardware register mapping or protocol conformance, and shall use explicitly unsigned integral or enumeration types.

- Do not rely on implementation-defined bit-field behavior.

joaomariolago · 2026-01-28T01:14:45Z

+
+## Style and naming
+
+- Avoid tabs, indent consistently (use 2 or four spaces, be consistent with the project).


Suggested change

- Avoid tabs, indent consistently (use 2 or four spaces, be consistent with the project).

- Avoid tabs; use spaces for indentation. The exact width (2 or 4 spaces) must follow the project standard and remain consistent within a file.

joaomariolago · 2026-01-28T01:18:10Z

+- Do not call virtual functions from constructors or destructors.
+- Use member initializer lists for non-static members.
+- Declare copy/assignment when owning pointers or nontrivial destructors.
+- Base classes with virtual functions must have virtual destructors.


Suggested change

- Base classes with virtual functions must have virtual destructors.

- Base classes with virtual functions must have virtual destructors, unless the class is

explicitly marked as `final`.

ES-Alexander · 2026-04-23T14:48:09Z

+- No spaces around `.` or `->`, and no spaces around unary operators.
+- Naming rules follow the project standard. If none is defined, use:
+  - `lower_snake_case` for functions and variables
+  - `UpperCamel_Case` for classes, structs, enums, and typedefs (e.g., `AP_Compass`)


Suggested change

- `UpperCamel_Case` for classes, structs, enums, and typedefs (e.g., `AP_Compass`)

- `UpperCamelCase` for classes, structs, enums, and typedefs

- Acronyms can be separated by underscores (e.g. `AP_AdvancedFailsafe`)

ES-Alexander · 2026-04-23T15:00:44Z

+  - `UpperCamel_Case` for classes, structs, enums, and typedefs (e.g., `AP_Compass`)
+  - lowercase constants and enumerators
+  - uppercase acronyms inside identifiers (e.g., `GCS_MAVLink`)
+  - use underscore for private properties


Do we expect to use lots of libraries in our embedded code?
I suspect the compiler would catch any name collisions caused by this, and it seems potentially valuable to indicate throughout the code when something is private 🤷‍♂️

ES-Alexander · 2026-04-23T15:01:39Z

+  - `UpperCamel_Case` for classes, structs, enums, and typedefs (e.g., `AP_Compass`)
+  - lowercase constants and enumerators
+  - uppercase acronyms inside identifiers (e.g., `GCS_MAVLink`)
+  - use underscore for private properties


Suggested change

- use underscore for private properties

- use a preceding underscore for private properties (e.g. `_internal_var`)

Not sure if this was the intent (or double preceding underscore, or one before + one after, etc), but it should be clarified.

ES-Alexander · 2026-04-23T15:05:30Z

+## Documentation
+
+- Document units in names or comments for physical quantities.
+- Prefer doxygen-style comments for C++ projects.


Do we also have preferences for other languages?

ES-Alexander · 2026-04-23T15:07:36Z

+- Prefer fixed-size arrays, if dynamic containers are needed, use project-approved
+  alternatives.
+- Avoid bit fields, use plain booleans.
+- Remove dead code, do not comment out unused code.


Is it acceptable/recommended to include "TODO" comments in the place of code that is not yet in use elsewhere?

ES-Alexander · 2026-04-23T15:13:10Z

+  alternatives.
+- Avoid bit fields, use plain booleans.
+- Remove dead code, do not comment out unused code.
+- Prefer multiplication over division for unit conversions.


How strong is this preference / how spelled out should conversions be?
As an example, should converting from degrees to radians be angle_deg * tau / 360, or angle_deg * 0.01745329251 (which then likely requires an explanatory comment), or something else? Or are they considered equivalent because the conversion factor is likely evaluated at compile time?

Suggested change

- Prefer multiplication over division for unit conversions.

- Prefer multiplication over division for unit conversions, unless it is less clear.

ES-Alexander · 2026-04-23T15:17:55Z

+
+## Portability and build
+
+- Target multiple embedded platforms when feasible, avoid vendor-locked toolchains.


Suggested change

- Target multiple embedded platforms when feasible, avoid vendor-locked toolchains.

- Target multiple embedded platforms when feasible.

- Avoid vendor-locked toolchains.

ES-Alexander · 2026-04-23T15:22:25Z

+
+- Avoid tabs, indent consistently (use 2 or four spaces, be consistent with the project).
+- Use braces for all control statements.
+- Braces for blocks on their own lines and aligned.


Does this include starting braces, and braces that are part of block continuations?

I'm personally more inclined to

if (condition) { ... } else { ... }

than

if (condition) { ... } else { ... }

patrickelectric added 2 commits January 27, 2026 16:04

guidelines: style: Fix typo

5db01dc

Signed-off-by: Patrick José Pereira <patrickelectric@gmail.com>

guidelines: embedded: first commit

1fd4ab5

Signed-off-by: Patrick José Pereira <patrickelectric@gmail.com>

joaomariolago suggested changes Jan 28, 2026

View reviewed changes

ES-Alexander suggested changes Apr 23, 2026

View reviewed changes

	- Prefer compile-time checksm add run-time checks for safety-critical paths.
	- Prefer compile-time checks, and add run-time checks only for safety-critical paths.

	- Keep data members private, avoid public/protected data in classes.
	- Keep member variables private; avoid use of public or protected member variables in C++ classes.

-- Avoid bit fields, use plain booleans.
+- Avoid using bit-fields for data packing or space optimization.
+- For general state and control logic, prefer plain boolean or integer members over bit-fields.
+- Bit-fields may be used only when required for hardware register mapping or protocol conformance, and shall use explicitly unsigned integral or enumeration types.
+- Do not rely on implementation-defined bit-field behavior.


		## Style and naming

		- Avoid tabs, indent consistently (use 2 or four spaces, be consistent with the project).

	- Avoid tabs, indent consistently (use 2 or four spaces, be consistent with the project).
	- Avoid tabs; use spaces for indentation. The exact width (2 or 4 spaces) must follow the project standard and remain consistent within a file.

	- Base classes with virtual functions must have virtual destructors.
	- Base classes with virtual functions must have virtual destructors, unless the class is
	explicitly marked as `final`.

	- `UpperCamel_Case` for classes, structs, enums, and typedefs (e.g., `AP_Compass`)
	- `UpperCamelCase` for classes, structs, enums, and typedefs
	- Acronyms can be separated by underscores (e.g. `AP_AdvancedFailsafe`)

	- use underscore for private properties
	- use a preceding underscore for private properties (e.g. `_internal_var`)

	- Prefer multiplication over division for unit conversions.
	- Prefer multiplication over division for unit conversions, unless it is less clear.


		## Portability and build

		- Target multiple embedded platforms when feasible, avoid vendor-locked toolchains.

	- Target multiple embedded platforms when feasible, avoid vendor-locked toolchains.
	- Target multiple embedded platforms when feasible.
	- Avoid vendor-locked toolchains.

Conversation

patrickelectric commented Jan 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants