mirror of
https://github.com/mytechnotalent/Embedded-Hacking.git
synced 2026-10-13 11:17:49 +02:00
55 lines
2.4 KiB
Markdown
55 lines
2.4 KiB
Markdown
---
|
|
name: embedded-c-standard
|
|
description: Use ONLY when writing, editing, or reviewing C firmware in a picokit project (firmware/src, firmware/include, firmware/tests). Enforces the strict C standard: no function over 8 executable lines, no blank lines inside a function body, a Doxygen block with @brief/@param/@return on every function, a fixed module layout and naming scheme, and a ban on em/en dashes. Run the bundled audit_c_standard.py before every commit.
|
|
---
|
|
|
|
# Embedded C standard (picokit)
|
|
|
|
This is non-negotiable and identical in every project in the series. There is
|
|
no variation between projects. If a rule is inconvenient, refactor; do not
|
|
exempt.
|
|
|
|
## Rules
|
|
|
|
1. No function longer than 8 executable lines. The audit counts every
|
|
non-blank, non-comment, non-brace line in the body, including continuation
|
|
lines of a wrapped statement. Split the work into a `static` helper.
|
|
2. No blank lines inside a function body. Separate logical steps with a
|
|
comment, never with a blank line.
|
|
3. Documentation lives in the header. Every function declaration in a `.h`
|
|
carries a Doxygen block with `@brief`, a `@param` for each parameter
|
|
(`@param void No parameters.` when there are none), and an `@return`. A
|
|
`static` function, which has no declaration, carries its Doxygen block in
|
|
the `.c`. Never duplicate the block in the `.c` for an exported function.
|
|
4. No U+2013 (en dash) or U+2014 (em dash) anywhere. Use the hyphen-minus `-`.
|
|
5. Every source file opens with the MIT header block: `Copyright (c) 2026 Kevin
|
|
Thomas`, `Author`, `Email`, `GitHub`, `File`, `Desc`, `Created`.
|
|
6. Every header uses an include guard `#ifndef <MODULE>_H` / `#define
|
|
<MODULE>_H` / `#endif // <MODULE>_H`.
|
|
7. Naming: files and modules `snake_case`; functions `module_action`; macros
|
|
`UPPER_SNAKE`; types `name_t`; file-scope statics `g_name`.
|
|
8. One responsibility per file: `src/<module>.c` with `include/<module>.h`.
|
|
All hardware access goes through a HAL seam so the host tests can substitute
|
|
mocks.
|
|
9. 79-column lines, four-space indent, no tabs.
|
|
|
|
## Layout
|
|
|
|
```
|
|
firmware/
|
|
src/ <module>.c
|
|
include/ <module>.h
|
|
tests/ host unit tests, mock/, harness/
|
|
CMakeLists.txt
|
|
scripts/ run_tests.py check_coverage.py build.sh
|
|
```
|
|
|
|
## Verify
|
|
|
|
Run the bundled audit from the repository root. Exit 0 is clean; any output is
|
|
a failure and must be fixed before the change is complete.
|
|
|
|
```bash
|
|
python3 .opencode/skill/embedded-c-standard/audit_c_standard.py
|
|
```
|