Naming and style¶
How Kokeb Labs code is named, laid out and formatted. The naming rules are enforced by
readability-identifier-naming in the org .clang-tidy, and formatting by the org
.clang-format. Decisions: ADR-0008 and, for drivers,
ADR-0012.
Prefixes¶
| Code | Namespace | Macros | Includes | CMake |
|---|---|---|---|---|
A chip driver (driver-<chip>) |
<chip> |
<CHIP>_*, Kconfig CONFIG_<CHIP>_* |
"<chip>.hpp" |
find_package(<chip>), <chip>::<chip>, options <CHIP>_* |
| kb-core | kb |
KB_*, Kconfig CONFIG_KB_* |
"kb/..." |
kb::utils, kb::rtos, kb::interfaces, kb::handlers; options KB_* |
kb-hal-common |
kb::hal |
KB_HAL_* |
"kb/hal/..." |
kb::hal |
A driver never carries the kb prefix or any other org prefix; the prefix belongs to kb-core and the shared HAL
only.
Namespaces¶
| Code | Namespace |
|---|---|
| A chip driver | <chip> (pca9685, tmc9660); internals in <chip>::detail |
| kb-core | kb, or kb::<area> (kb::can) |
kb-hal-common |
kb::hal |
| A board HAL | <board>; the bind in <board>::bsp |
| A product | <board>::app |
Namespaces are lower case. using namespace is not allowed in headers. Anonymous namespaces are for .cpp-local
helpers only.
Identifiers¶
| Kind | Style | Examples |
|---|---|---|
| Classes, structs, enums, unions, type aliases, concepts | PascalCase |
Zp100Handler, Config, I2cPort |
| A chip driver class | the part number | PCA9685, TMC9660 |
| Template parameters | PascalCase |
Port, Derived, SpiType |
| Functions and public / protected methods | PascalCase |
Initialize(), ReadPressurePa(), SetDuty() |
| Private methods | camelBack |
writeReg(), selectBank() |
| Parameters and local variables | snake_case |
channel, timeout_ms |
| Public data members (struct fields) | snake_case |
config.ready_timeout_ms |
| Private and protected data members | snake_case_ |
initialized_, bus_mutex_ |
Constants (constexpr, static const, global const) |
kPascalCase |
kNumChannels, kDefaultAddress |
| Enumerators | PascalCase |
Error::NotInitialized, Oversampling::X8 |
| Macros | UPPER_CASE, prefixed with the repository or part |
PCA9685_VERSION_MAJOR, CONFIG_ZP100_ODR_HZ, KB_ENABLE_PCA9685 |
| Files | as the main type: PascalCase in kb-core and HALs (Zp100Handler.h); <chip>_<part>.hpp in drivers |
pca9685_i2c_interface.hpp |
Allowed exceptions, also allowed by the tidy config:
- Datasheet names in
UPPER_CASEfor register addresses, bit fields and enumerators that mirror the datasheet (MODE1,PRE_SCALE,GEN_CFG1), and forGpioSignal::ACTIVE/INACTIVE. - Vocabulary-type members
ok(),begin(),end(),size(),data(),empty(), soResult<T>and containers read like the standard library. - C-style APIs kb-core keeps: the
os_*functions inkb::rtosand thekb_*_ttypes inkb::interfaces. New code does not add to them. - Host test cases named
test_<what>intests/.
Verbs and units¶
Read*touches the bus;Get*returns cached state and never does I/O;Set*/Write*change the chip;Is*/Has*returnbooland do no I/O.- Quantities carry their unit as a suffix, in the identifier's own case:
| Unit | In PascalCase |
In snake_case |
|---|---|---|
| milliseconds, microseconds, seconds | Ms, Us, S |
_ms, _us, _s |
| hertz, kilohertz | Hz, Khz |
_hz, _khz |
| millivolts, volts | Mv, V |
_mv, _v |
| milliamps, microamps, amps | Ma, Ua, A |
_ma, _ua, _a |
| pascals, degrees Celsius | Pa, C |
_pa, _c |
| revolutions per minute, degrees | Rpm, Deg |
_rpm, _deg |
| percent, raw counts | Pct, Counts |
_pct, _counts |
SetHitCurrentMa(uint16_t current_ma), ReadTemperatureC(), timeout_ms. Not _mA, MilliAmps or a Unit
enum parameter.
- SI base units and integers are preferred. A float in a public API states its unit like any other value.
Include roots and headers¶
- One include root per kb-core part:
#include "kb/interfaces/BaseSpi.h",#include "kb/rtos/RtosMutex.h",#include "kb/utils/Status.h". Drivers use their flatinc/:#include "pca9685.hpp". Relative paths that climb out of a repository or part ("../../drivers/...") are not allowed. - Every header has an
#ifndefinclude guard, never#pragma once(MISRA C++:2023 Rule 19.2.1). Only comments come before#ifndef GUARD/#define GUARD, and#endifis the last line. The guard is<NAME>_<FILE_STEM>_<EXT>in upper case: the repository's name (the chip, or the library's CMake package), the file name without its extension in snake case, and the extension, with the name not repeated when the stem already starts with it:
| File | Guard |
|---|---|
inc/ads7952.hpp |
ADS7952_HPP |
inc/ads7952_types.hpp |
ADS7952_TYPES_HPP |
inc/max22200_spi_interface.hpp |
MAX22200_SPI_INTERFACE_HPP |
src/ads7952.ipp |
ADS7952_IPP |
inc/ads7952_version.h.in (configured) |
ADS7952_VERSION_H |
tests/mock_ads7952.hpp |
ADS7952_MOCK_ADS7952_HPP |
inc/ring/MovingAverage.h in ring_buffer |
RING_BUFFER_MOVING_AVERAGE_H |
No leading underscore and no double underscore: those names are reserved. No #pragma of any kind and no
_Pragma; compiler options live in the build. python checks/source_checks.py guard --repo . <path> prints the
guard a file needs, and python checks/source_checks.py scan --repo . runs the check CI runs
(KB-CPP-019).
- Include order: the file's own header, then standard headers, then other repositories, then this repository;
one blank line between groups. clang-format sorts within a group.
- A header includes what it uses and compiles on its own.
Formatting¶
config/.clang-format: LLVM base, 2-space indent, 100-column limit, pointer and
reference attached to the type (uint8_t* data), attached braces, short functions only when empty, template
declarations on their own line.
The column limit is 100 everywhere.
Markdown wraps at 120 columns (markdownlint MD013, tables and code blocks exempt).
Static analysis¶
config/.clang-tidy enables bugprone-*, clang-analyzer-*, cppcoreguidelines-*,
modernize-*, performance-*, portability-* and readability-*, turns off the checks that fight register-level
code (each with its reason in the file), and sets the naming rules above.
Using the configs in a repository¶
- Copy both files into the repository's
_config/unchanged. Do not add root copies or symlinks (ADR-0011); every tool is given the path:clang-format --style=file:_config/.clang-format,clang-tidy --config-file=_config/.clang-tidy. Editors that find the files only by name (clangd, CLion) use a local copy listed in.gitignore. - Point the lint workflow at them:
uses: kokeb-labs/ci-tools/.github/workflows/ru-cpp-lint.yml@v1
with:
clang_version: "20"
clang_format_config: "_config/.clang-format"
clang_tidy_config: "_config/.clang-tidy"
The shared workflow links the files into its own checkout; the repository carries no link.
3. Fix findings in new and changed code. Existing findings are fixed in their own PRs, not mixed into features.
4. Suppress a finding only with // NOLINT(<check>): <reason> or // NOLINTNEXTLINE(<check>): <reason>. A bare
NOLINT is not allowed.
A rule that is wrong for every repository is changed here, in both configs and on this page together.
Comments¶
- Public API is documented with Doxygen (
///or/** */): what it does, parameters with units, theErrororStatusvalues it returns, and whether it does I/O. See docs.md. - Comments say why. Datasheet references name the section or table (
SBASB22 Table 7-12). - No commented-out code, no
TODOwithout an issue link, no author or date banners, no tool attribution lines.