Code Guidelines

The specification of this standard exists to document and define the organisation and naming convention of code to create a well structured, cohesive project.

Warning

This document is grossly out of date and currently included only for the sake of editing in the future. Some information may still apply, however you should not consider these guidelines gospel.

Formatting

For formatting the project it is recommended that clang-format is used with the following settings configured in the .clangd project file:

AlignAfterOpenBracket: BlockIndent
AlignOperands: AlignAfterOperator
AlignTrailingComments:
  Kind: Always
  OverEmptyLines: 4
AllowAllParametersOfDeclarationOnNextLine: false
AllowShortLoopsOnASingleLine: true
BinPackParameters: false
BraceWrapping:
  AfterFunction: false
BreakBeforeBraces: Custom
BreakBeforeBinaryOperators: NonAssignment
ColumnLimit: 0
ReflowComments: true

Library Functions

Convention:
Functions should be proceeded by the library name separated by a single underscore. The library name in this case should follow proper capitilisation, particularly in the case of initialisms and acronyms; e.g. MemBuff_append(), LoRa_send(), CAN_init().

C does not provide functionality for namespacing or mangling, meaning it is possible for name conflicts that would cause failure to compile in the case that two libraries share functions or defintions of the same name.

Take, for example, a situation where CAN and SPI libraries both implement a function sendData(). Attempting to compile the project will error out when linking these libraries due to name conflict.

Struct Encapsulation

Convention:
Global variables should not be used within libraries. If a resource is required to be shared across functions, place them within a library struct with appropriate intitialisation. These structs should follow the same naming convention as library functions. It is not necessary, though it is preferred, to include library functions as pointers within these structs.

As mentioned, C does not support namespaces. Global variables can and will cause logic errors when multiple libraries implement globals sharing common names. The compiler may issue a warning however multiple definitions are legal in C and will not throw an error at compile time, this can be quite difficult to debug.

For an example see the MemBuff implementation. An example skeleton of a library struct implementation can be found here; You may find it easier to copy the example directory entirely and simply rename the files and code elements to align with the library you are working on.