Skip to content

Latest commit

 

History

History
92 lines (63 loc) · 4.2 KB

4_naming.md

File metadata and controls

92 lines (63 loc) · 4.2 KB
Raw

Additional Naming Suggestions

Read base rules.

Class Name Suffixes

Class names often have a suffix term that indicates the purpose (and not only the topic) of that class. While there seems to be no common agreement on the notation, we find the following distinction useful:

  • Factory/Builder: creates objects and transfers ownership (e.g. to a Manager).
  • Manager: stateless, owns and provides access to same-type objects (e.g. SensorManager).
  • Controller: stateful, handles communication between different objects (e.g. FlightController).
  • Handler: waits for and processes a single-type object, without owning it (e.g. EventHandler).

High-level Scopes (= Module/Package/Namespace)

The names for packages or namespaces, which should prevent name clashes, should be short as they are used often within the code. In this case, choosing an abbreviation or acronym makes sense.

Use physical units as type names.

In embedded systems, you often have to deal with physical quantities. To make clear which unit a certain variable has, you should define your own (sub)types for physical units based on numerical type, such as Meter and Second from Float, and then declare variables as Meter safety_distance = 5.0;.

Use abbreviations cautiously and only common ones.

To abbr. or not to abbreviate? Truth is, neither GetTheLatestWebSiteAccessTimeInMilliseconds(), nor pm_rcv_bat_stat() are reader friendly. Use abbreviations only for small scopes, function arguments, or in combination with full names (move_cmd). Avoid abbreviations if they only save one character (usr), are too cryptic (cmp), or can be confused with other terms (tmp). If you use them, stick to the following common abbreviations (already a lot):

👆 List of common coding abbreviations
Abbr. Meaning Abbr. Meaning
arg argument mid middle
app application min minimum
auth authentication mem memory
avg average mon monitor
bat battery msg message
buf buffer net network
cb callback num number
cfg config. obj object
clk clock pkg package
col column pkt packet
cnt counter pos position
cmd command pt point
ctx context ptr pointer
dev device pwr power
doc document px pixel
drv driver rnd round
dt delta time reg register
el element rot rotation
env environment sep separator
err error std standard
exc exception str string
fh file handler sys system
fmt format tmr timer
hdr header ts timestamp
hex hexadecimal val value
img image var variable
idx index win window
len length
lib library
lvl level
max maximum

Per-second/minute acronyms: fps (frame), rpm (rotations), mps (meter) Avoid these abbr.: tmp, fun, chk, dis, usr, cpy, tgl, txt, pc, mov, sec

 
👆 List of Domain Specific Abbreviations

Abbreviations and Acronyms in Embedded Systems:

  • Sensors: IMU (=ACC, GYR, MAG), BARO, TEMP, GPS (= lat, lon, alt)
  • Buses: USB, CAN, SPI, I2C, UART, ETH, PCI
  • Processor: CPU, GPU, MCU: RAM, ROM, ISR, ADC, DAC, RTC, CLK, DMA
  • Software: API, CLI, GUI, HAL, OS, VM, PID, UID, LSB, MSB, CRC