2.2. C Coding Guidelines
These coding guidelines MUST be applied to all C
source and header
files.
The source files MUST be successfully checked by running the waf command
check_guidelines
before files can be merged into the master branch of the
repository.
2.2.1. General Information
Generally foxBMS 2 uses for the embedded code
1TBS.
This is checked by clang-format
. The clang-format
configuration is
found in ./.clang-format
. The C
source and header files can be checked
by running waf check_guidelines
. Using VS Code files are automatically
saved correctly (see Creating a Workspace) when clang-format
is
installed (see Software Prerequisites) using Ctrl-S.
Warning
The style of third party sources (generated HAL sources in
build/bin/src/hal/**
and src/os
) should not be changed.
To save without reformatting use Ctrl-K + Ctrl-Shift-S.
The following list shows more detailed rules for foxBMS 2. Every rule has some context and/or rationale and notes that clearly state the rules, followed by a correct examples. If it supports the clarification incorrect examples may also be shown.
The following rules generally apply and follow the naming schema
C:<ongoing-number>
.
2.2.2. Filenames (C:001
)
Additional to the general file naming rules the following MUST be applied.
File name rules
The general file naming rules MUST be applied (see Section 2.1.1).
Assembler
source files MUST use.asm
as file extension.C
source files MUST use.c
as file extension.C
header files MUST use.h
as file extension.Software functionalities (e.g., low level driver, algorithms, etc…) should be split in configuration files and the actual implementation. These configuration files MUST end with
_cfg.c
or_cfg.h
respectively.
For example the valid file names for an implementation of driver
, that is
split into a driver and a configuration part, is:
driver.c
driver.h
driver_cfg.c
driver_cfg.h
2.2.3. Header (C:002
)
C file header
C source and header files MUST start with the following header:
1/**
2 *
3 * @copyright © 2010 - 2021, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
4 * All rights reserved.
5 *
6 * SPDX-License-Identifier: BSD-3-Clause
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright notice, this
12 * list of conditions and the following disclaimer.
13 *
14 * 2. Redistributions in binary form must reproduce the above copyright notice,
15 * this list of conditions and the following disclaimer in the documentation
16 * and/or other materials provided with the distribution.
17 *
18 * 3. Neither the name of the copyright holder nor the names of its
19 * contributors may be used to endorse or promote products derived from
20 * this software without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 *
33 * We kindly request you to use one or more of the following phrases to refer to
34 * foxBMS in your hardware, software, documentation or advertising materials:
35 *
36 * - ″This product uses parts of foxBMS®″
37 * - ″This product includes parts of foxBMS®″
38 * - ″This product is derived from foxBMS®″
39 *
40 */
2.2.4. Linelength (C:003
)
Linelength rules
Each line of text in your code SHOULD be at most 120 characters long. A line MAY exceed 120 characters if it is
a comment line which is not feasible to split without harming readability, ease of cut and paste or auto-linking, e.g., if a line contains an example command or a literal URL longer than 120 characters or
raw-string literal with content that exceeds 120 characters. Except for test code, such literals should appear near the top of a file.
Each line of doxygen comment in your code SHOULD be at most 80 characters long. A line MAY exceed 80 characters if it is
a comment line which is not feasible to split without harming readability, auto-linking, e.g., a literal URL longer than 80 characters or
a raw-string literal with content that exceeds 80 characters.
2.2.5. File level doxygen (C:004
)
Doxygen is used to create an API documentation.
File level doxygen rule
Every file MUST be documented with doxygen style comments in order to be properly processed by doxygen.
The file level doxygen MUST come after the license header separated by a blank line.
The following doxygen parameters MUST be included in every file:
@file
,@author
,@date
,@updated
,@ingroup
,@prefix
,@brief
,@details
All doxygen parameter arguments MUST be whitespace aligned.
After
@prefix
,@brief
and@details
there MUST be an blank line.The
@prefix
argument MUST use between two and five uppercase alphanumericals starting with an uppercase character.The
@prefix
argument MAY use abbreviations.The
@prefix
and@ingroup
arguments MUST use alphanumeric uppercase characters including underscores.The
@date
argument MUST be an ISO 8601 date followed by(date of creation)
.The
@updated
argument MUST be an ISO 8601 date followed by(date of last update)
.
Listing 2.2 shows how this looks for a file c-004.c
.
1/**
2 * @file c-004.c
3 * @author foxBMS Team
4 * @date 2021-04-06 (date of creation)
5 * @updated 2021-04-06 (date of last update)
6 * @ingroup SOME_GROUP
7 * @prefix ABC
8 *
9 * @brief Implementation of some software
10 *
11 */
2.2.6. Include guard (C:005
)
An include guard, is a construct used in C
to avoid the problem
of multiple inclusion when dealing with the include directive.
Include guard rules
All header files MUST implement include guards to prevent multiple inclusions.
The include guard MUST come right after the file level doxygen comment.
The format of the include guard MUST consist of the prefix
FOXBMS__
, followed by the file name in uppercase and then followed by_H_
.There MUST NOT be a blank line between
#ifndef
and#define
.There MUST be a blank line after
#define
.
Listing 2.3 shows how this looks for a file c-005.h
, where
the include guard would be FOXBMS__C_005_H_
.
1#ifndef FOXBMS__C_005_H_
2#define FOXBMS__C_005_H_
3
4/* some code */
5
6#endif /* FOXBMS__C_005_H_ */
2.2.7. C Sections (C:006
)
C sections
Every .c and .h file MUST contain all specific section comments in the
correct order.
There are different section comments for sources and headers for source
files (files in src/**
) and test files (files in tests/unit/**
).
Listing 2.4 shows how this looks for a file c-006-source.h
.
1#ifndef FOXBMS__C_006_SOURCE_H_
2#define FOXBMS__C_006_SOURCE_H_
3
4/*========== Includes =======================================================*/
5
6/*========== Macros and Definitions =========================================*/
7
8/*========== Extern Constant and Variable Declarations ======================*/
9
10/*========== Extern Function Prototypes =====================================*/
11
12/*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
13
14#endif /* FOXBMS__C_006_SOURCE_H_ */
Listing 2.5 shows how this looks for a file c-006-source.c
.
1/*========== Includes =======================================================*/
2
3/*========== Macros and Definitions =========================================*/
4
5/*========== Static Constant and Variable Definitions =======================*/
6
7/*========== Extern Constant and Variable Definitions =======================*/
8
9/*========== Static Function Prototypes =====================================*/
10
11/*========== Static Function Implementations ================================*/
12
13/*========== Extern Function Implementations ================================*/
14
15/*========== Externalized Static Function Implementations (Unit Test) =======*/
Listing 2.6 shows how this looks for a file ./test/c-006-test.h
.
1#ifndef FOXBMS__C_006_TEST_H_
2#define FOXBMS__C_006_TEST_H_
3
4/*========== Includes =======================================================*/
5
6/*========== Macros and Definitions =========================================*/
7
8#endif /* FOXBMS__C_006_TEST_H_ */
Listing 2.7 shows how this looks for a file ./test/c-006-test.c
.
1#ifndef FOXBMS__C_006_TEST_C_H_
2#define FOXBMS__C_006_TEST_C_H_
3
4/*========== Includes =======================================================*/
5
6/*========== Definitions and Implementations for Unit Test ==================*/
7
8/*========== Setup and Teardown =============================================*/
9
10/*========== Test Cases =====================================================*/
11
12#endif /* FOXBMS__C_006_TEST_C_H_ */
2.2.8. Includes (C:007
)
Includes are used to insert the contents of a second file into the original file. There are two scenarios to be considered for file includes. They distinguish if the software module provides configuration files or not.
Include rules
All includes MUST be listed after the
includes
marker.Only required includes MUST be added.
Forward declarations MUST NOT be used. Instead, you MUST
#include
all the headers that declare functions you need.Configuration header files MUST apply the following order of includes:
Include
general.h
A blank line
Add required includes in alphabetical order according to rule
Other header files MUST apply the following order of includes:
Include corresponding configuration header if it exists, otherwise include
general.h
A blank line
Add required includes in alphabetical order according to rule
Source files MUST apply the following order or includes:
Include corresponding header file
A blank line
Add required includes in alphabetical order according to rule
The rule for sorting required includes is (omit block if empty):
unity.h
(for unit tests)A blank line
Generated Mock-header (for unit tests)
A blank line
Any
*_cfg.h
that is includedA blank line
HAL-headers starting with
HL_
-header files and ending withti_
-header filesA blank line
FreeRTOS headers starting with
FreeRTOS.h
A blank line
All other required headers except Mocks
Listing 2.8, Listing 2.9, Listing 2.10 and Listing 2.11 show how includes MUST be added.
1#ifndef FOXBMS__C_007_ABC_CFG_H_
2#define FOXBMS__C_007_ABC_CFG_H_
3
4#include "general.h"
5
6#include "required_additional_header.h"
7#include "required_additional_header2.h"
8
9#endif /* FOXBMS__C_007_ABC_CFG_H_ */
1#include "c-007_abc_cfg.h"
2
3#include "some_other_required_header.h"
4#include "some_other_required_header2.h"
1#ifndef FOXBMS__C_007_ABC_H_
2#define FOXBMS__C_007_ABC_H_
3
4#include "c-007_abc_cfg.h"
5
6#include "required_different_header.h"
7#include "required_very_different_header.h"
8
9#endif /* FOXBMS__C_007_ABC_H_ */
1#include "c-007_abc.h"
2
3#include "FreeRTOS.h"
4#include "queue.h"
5
6#include "first_used_header_1.h"
7#include "second_used_header.h"
8#include "xyz.h"
2.2.9. Scoping (C:008
)
Scope rules
All functions, variables, typedefs, macros etc. MUST be declared in the narrowest scope possible (function, file, global).
If a function, macro, typedef or variable is used by multiple files/modules, declare it public.
If a function, macro, typedef or variable is only used within a file, declare it static.
If a variable is only used within a function, declare it inside the function.
1#include "c-008.h"
2
3static uint32_t abc_staticVariable = 0; /*!< File static variable that is used within multiple functions */
4
5uint32_t abc_globalVariable; /*!< Important global variable that is used by multiple files/modules */
6
7/**
8 * @brief Function to do important stuff in this file/module.
9 */
10static void ABC_StaticImportantFunction(void);
11
12static void ABC_StaticImportantFunction(void) {
13 uint32_t temporaryVariable = 0; /* Temporary variable to do calculations in this function */
14}
15
16extern void ABC_GlobalImportantFunction(void) {
17}
2.2.10. Function names (C:009
)
Function naming rules
Function names MUST start with the uppercase module prefix followed by a capital letter with capital letters for each new word (Pascal Case).
The only exception are the unit-test-functions which start with
test
due to ceedling requiring it.Function names SHOULD start with a verb followed by a noun (verb-noun pattern). After the verb-noun pattern additional words MAY follow.
Listing 2.13, shows correctly named functions.
1static void ABC_ImportantFunction(void);
2static void ABC_EvenMoreImportantFunction(void);
3
4static void ABC_ImportantFunction(void) {
5}
6static void ABC_EvenMoreImportantFunction(void) {
7}
2.2.11. Function scopes (C:010
)
Function scope rules
Global and static functions MUST be declared respectively with the keywords
extern
orstatic
. This keyword MUST be used for the function prototype declaration and the function definition.Global function prototypes MUST be declared in the header file.
Static function prototypes MUST be declared in the source file.
Listing 2.14 and
Listing 2.15 show correctly declared and
implemented functions on the header abc.h
and respective source file
abc.c
.
2.2.12. Function doxygen documentation (C:011
)
Function scope rules
The doxygen documentation describing each function MUST be placed above the prototype declaration.
All function prototype declarations and function implementations MUST be placed in the correct sections in the source/header files.
The following doxygen parameters MUST be documented for every function:
@brief
and@details
.Doxygen parameter
@return
MUST be documented if the return type is not of typevoid
.Function arguments MUST be documented using the doxygen parameter
@param
.All doxygen parameter arguments MUST be whitespace aligned.
Listing 2.14 and
Listing 2.15 show doxygen documented functions
in a header file c-011.h
and source file c-011.c
.
c-011.h
, placed in the Extern Function Prototypes
section. 1#ifndef FOXBMS__C_011_H_
2#define FOXBMS__C_011_H_
3
4#include "general.h"
5
6/**
7 * @brief Does this and that
8 * @details Detailed description of this function
9 * @return some uint8_t which describes xyz
10 */
11extern uint8_t ABC_ImportantFunction(void);
12
13#endif /* FOXBMS__C_011_H_ */
c-011.c
, placed in the Extern Function Implementations
section. 1#include "c-011.h"
2
3/**
4 * @brief Does something
5 * @details Detailed description of this function
6 * @return some uint8_t which describes xyz
7 */
8static uint8_t ABC_AnotherFunction(void);
9
10static uint8_t ABC_AnotherFunction(void) {
11 /* code */
12 return 0;
13}
14
15extern uint8_t ABC_ImportantFunction(void) {
16 /* code */
17 return 0;
18}
2.2.13. Function return statement (C:012
)
Return statement rules
Parentheses surrounding the return expression SHOULD NOT be used. Use parentheses in return expressions only in places where you would use them in normal assignments.
Listing 2.16 shows how to correctly use parentheses and the return statement.
1#include "general.h"
2
3static uint8_t ABC_ReturnAbc(void);
4static uint8_t ABC_ReturnDef(uint8_t another_condition, uint8_t some_long_condition);
5
6static uint8_t ABC_ReturnAbc(void) {
7 uint8_t result = 0;
8 return result; /* No parentheses in the simple case. */
9}
10
11static uint8_t ABC_ReturnDef(uint8_t another_condition, uint8_t some_long_condition) {
12 uint8_t result = 0;
13 /* Parentheses OK to make a complex expression more readable. */
14 /* clang-format off */
15 return (some_long_condition &&
16 another_condition);
17 /* clang-format on */
18}
2.2.14. Function calls (C:013
)
Function call rules
Multiple arguments SHOULD be put on a single line to reduce the number of lines necessary for calling a function unless there is a specific readability problem. Some style guides require formatting strictly one argument on each line for simplifying editing the arguments. However, we prioritize readability over the ease of editing arguments, and most readability problems are better addressed with the following techniques.
If the arguments do not all fit on one line, they MAY be broken up onto multiple lines, with each subsequent line aligned with the first argument.
Arguments MAY also be placed on subsequent lines with an eight space indent.
If having multiple arguments in a single line decreases readability due to the complexity or confusing nature of the expressions that make up some arguments, it is RECOMMENDED to
create variables that capture those arguments in a descriptive name,
put the confusing argument on its own line with an explanatory comment.
If there is still a case where one argument is significantly more readable on its own line, then put it on its own line. The decision should be specific to the argument which is made more readable rather than a general policy.
Sometimes arguments form a structure that is important for readability. In those cases, it is RECOMMENDED to format the arguments according to that structure
Different correct ways to call functions with multiple parameters or long function names are given in Listing 2.17.
1#include "general.h"
2
3static uint8_t x1 = 0;
4static uint8_t x2 = 0;
5static uint8_t x3 = 0;
6static uint8_t y1 = 0;
7static uint8_t y2 = 0;
8static uint8_t y3 = 0;
9static uint8_t z1 = 0;
10static uint8_t z2 = 0;
11static uint8_t z3 = 0;
12
13static uint8_t scores[5] = {0};
14static uint8_t bases[5] = {0};
15
16/* clang-format off */
17static void ABC_TransformMyWidget(
18 uint8_t x1, uint8_t x2, uint8_t x3,
19 uint8_t y1, uint8_t y2, uint8_t y3,
20 uint8_t z1, uint8_t z2, uint8_t z3);
21/* clang-format on */
22
23static int16_t ABC_DoSomething(int16_t var, int16_t x, int16_t y, int16_t z);
24
25/* clang-format off */
26static void ABC_TransformMyWidget(
27 uint8_t x1, uint8_t x2, uint8_t x3,
28 uint8_t y1, uint8_t y2, uint8_t y3,
29 uint8_t z1, uint8_t z2, uint8_t z3) {
30}
31/* clang-format on */
32
33static int16_t ABC_DoSomething(int16_t var, int16_t x, int16_t y, int16_t z) {
34 return 0;
35}
36
37int16_t ABC_SomeFunction(uint8_t x, uint8_t y, uint8_t z) {
38 /* use variable to capture value, before passing to function */
39 int16_t myHeuristic = scores[x] * y + bases[x];
40 int16_t result = ABC_DoSomething(myHeuristic, x, y, z);
41
42 /* place confusing argument on own commented line and all other parameters
43 also on an own line */
44 result += ABC_DoSomething(
45 scores[x] * y + bases[x], /* Score heuristic. */
46 x,
47 y,
48 z);
49
50 /* Its a matrix, and therefore it makes sense to format the arguments as a matrix */
51 /* clang-format off */
52 ABC_TransformMyWidget(x1, x2, x3,
53 y1, y2, y3,
54 z1, z2, z3);
55 /* clang-format on */
56 return result;
57}
2.2.15. Additional function rules (C:014
)
Most of the following rules are checked by the clang-format configuration of the project. If a rule is not checked automatically it is indicated.
Additional Function rules
The open parenthesis MUST be on the same line as the function name.
There MUST NOT be a space between the function name and the open parenthesis.
There MUST NOT be a space between the parentheses and the parameters.
The open curly brace MUST be on the end of the last line of the function declaration, not the start of the next line.
The close curly brace MUST be either on the last line by itself or on the same line as the open curly brace.
There MUST be a space between the close parenthesis and the open curly brace.
Spaces after the open or before the close parenthesis MUST NOT be added.
All parameters SHOULD be aligned if possible.
If you cannot fit the return type and the function name on a single line, you MUST break between them.
If you break after the return type of a function declaration or definition, you MUST not indent.
You SHOULD use describing parameter names. (Not checked by clang-format)
2.2.16. Function parameter checking (C:015
)
Function parameter checking
Input values of function parameters SHOULD be checked at the beginning of a function if possible.
Pointers passed as parameters MUST be checked against
NULL_PTR
.
Parameter checking is shown in Listing 2.18.
1#include "c-015.h"
2
3extern uint32_t ABC_ArrayAverage(uint8_t *pArray, uint8_t arrayLength) {
4 uint32_t sum = 0u;
5
6 FAS_ASSERT(pArray != NULL_PTR);
7 FAS_ASSERT(arrayLength > 0u);
8
9 for (uint16_t i = 0u; i < arrayLength; i++) {
10 sum += pArray[i];
11 }
12 sum /= arrayLength;
13 return sum;
14}
2.2.17. Variable names (C:016
)
Variable naming rules
Global and static variables MUST be commented with a doxygen style comment.
Variable names (including function parameters) MUST start with a lowercase letter and are written in “camel Case”.
If the scope of the variable is at least file wide (more than function scope) or if the variable is declared static it MUST start with the module prefix in lowercase letters. A variable representing a physical unit is followed by a suffix with the SI-unit symbol
_<unit>
(e.g._mA
for milliampere orK
for Kelvin). Exceptions are non-ASCII symbols as_perc
for%
,_degC
for°C
andu
forμ
.A doxygen comment explaining what this variable is used for MUST be added to all static and global variables.
1#include "general.h"
2
3static uint32_t abc_staticVariable = 0u; /*!< Static variable -> prefix + doxygen comment */
4static int32_t abc_packSoc_perc = 0; /*!< Static variable representing physical unit -> prefix + suffix + doxygen */
5
6extern uint32_t abc_globalVariable; /*!< Global variable -> prefix + doxygen comment */
7
8static void ABC_StaticImportantFunction(void);
9
10static void ABC_StaticImportantFunction(void) {
11 uint8_t maxValue = 32u; /* Temporary variable to do calculations in this function */
12 uint32_t maximumTemporaryVoltage_mV = 0u; /* Variable representing physical unit -> suffix */
13 maxValue--;
14
15 /* Local loop counter */
16 for (uint8_t counter = 0u; counter < maxValue; counter++) {
17 /* Do something.... */
18 }
19}
2.2.18. Constant names (C:017
)
Constant rules
Constant variables MUST be commented with a doxygen style comment.
Constant variables MUST be named with a module prefix and a leading
k
followed by camel case.Underscores MAY be used as separators in rare cases where capitalization cannot be used for separation.
1#include "general.h"
2
3const static uint16_t abc_kDaysInAWeek = 7; /*!< Number of days in a week */
2.2.19. Pointer rules (C:018
)
Pointer rules
The general variable name rules apply (see Variable names (C:016)).
Variables used for pointers MUST be prefixed with a leading
p
in the case of a pointer to a variable andfp
in the case of a function pointer, followed by camel Case. When declaring a pointer variable or argument, the asterisk MUST be placed adjacent to the variable name.As function-pointer syntax can get complicated and lead to errors, a function pointer MUST use a typedef. The typedef of a function has to use the suffix
_f
.Spaces around
.
or->
MUST NOT be used when accessing pointers. The following listing contains examples of correctly-formatted pointer and reference expressions:
1#include "general.h"
2
3typedef struct INIT_STRUCT {
4 uint32_t value;
5} INIT_STRUCT_s;
6
7typedef uint8_t SOME_FUNCTION_TYPE_f(void); /* typedef of a function type */
8uint32_t myVariable = 0; /* local uint32_t variable */
9static uint32_t *abc_pMyPointer = NULL_PTR; /* static uint32_t pointer */
10static INIT_STRUCT_s abc_initStruct = {0}; /* static init struct */
11INIT_STRUCT_s *pInitStruct = NULL_PTR; /* local pointer to some init struct */
12SOME_FUNCTION_TYPE_f *fpMyFunction; /* local function pointer using a typedef */
13
14void ABC_AssignSomeValue() {
15 abc_pMyPointer = &myVariable;
16 myVariable = *abc_pMyPointer;
17 myVariable = abc_initStruct.value;
18 myVariable = pInitStruct->value;
19}
2.2.20. Variable initialization (C:019
)
Variable initialization rules
All variables SHOULD be initialized at the point of their definition. If this is not done it MUST be commented why it is not done.
All variables MUST be initialized with the correct type.
Only one variable MUST be initialized or declared per line.
No multi-definitions MUST be used.
For the initialization, the correct suffixes for unsigned, signed and floating-point types MUST be used. See Table 2.11 for details.
Pointers MUST be initialized with
NULL_PTR
if no other valid initialization is possible.
Type |
Suffix |
---|---|
uint8_t |
|
uint16_t |
|
uint32_t |
|
uint64_t |
|
int8_t |
|
int16_t |
|
int32_t |
|
int64_t |
|
1#include "general.h"
2
3/* Initialization example for structs */
4typedef struct POINT {
5 float x;
6 float y;
7 float z;
8} POINT_s;
9
10typedef struct PATH {
11 POINT_s point;
12 uint32_t timestamp;
13 uint32_t previousTimestamp;
14 uint8_t name[16];
15} PATH_s;
16
17/* Initialization for variables */
18uint8_t myVar0 = 10u;
19uint16_t myVar1 = 10u;
20uint32_t myVar2 = 10u;
21uint64_t myVar3 = 10uLL;
22int8_t myVar4 = -10;
23int16_t myVar5 = -10;
24int32_t myVar6 = -10;
25int64_t myVar7 = -10LL;
26
27/* Initialization example for arrays */
28uint8_t myArrayA[] = {1, 2, 3}; /* Array has type uint8_t[3] and holds 1,2,3 */
29uint8_t myArrayC[5] = {0}; /* Array has type uint8_t[5] and holds 0,0,0,0,0 */
30
31uint8_t myArrayD[4][3] = {
32 /* array of 4 arrays of 3 uint8_t's each (4x3 matrix) */
33 {1}, /* row 0 initialized to {1, 0, 0} */
34 {0, 1}, /* row 1 initialized to {0, 1, 0} */
35 {[2] = 1}, /* row 2 initialized to {0, 0, 1} */
36}; /* row 3 initialized to {0, 0, 0} */
37
38POINT_s myPoint = {1.2, 1.3}; /* p.x=1.2, p.y=1.3, p.z=0.0 */
39
40PATH_s myPath = {80.0f, 127.0f, -37.0f, 0, 1, "test"}; /* 80.0f initializes myPath.point.x */
41 /* 127.0f initializes myPath.point.y */
42 /* -37.0f initializes myPath.point.z */
43 /* 0 initializes myPath.timestamp */
44 /* 1 initializes ex.in_u.a8[3] */
45 /* "test" initializes name[0-3] */
46 /* name[4-15] are set to 0 */
2.2.21. Hexadecimal values (C:020
)
Hexadecimal values rules
Hexadecimal digits MUST be written in uppercase letters.
1#include "general.h"
2
3uint8_t myVar = 0xFFu;
4int8_t myOtherVar = 0xAA;
2.2.22. Floating-point values (C:021
)
Floating-point values rules
Floating-point literals MUST always have a radix point, with digits on BOTH sides, even if they use exponential notation. Readability is improved if all floating-point literals take this familiar form, as this helps ensure that they are not mistaken for integer literals, and that the E/e of the exponential notation is not mistaken for a hexadecimal digit.
float
types SHOULD be used wherever possible as the float operations are performed in hardware while double operations are not.
Type |
Suffix |
---|---|
float |
|
double |
|
1static const float kEuler = 2.71828f;
2static const double kPi = 3.141592;
3static double number = 1248.0e6;
4static long double largeNumber = -0.5L;
2.2.23. Structs (C:022
)
Struct rules
Structs MUST be commented with a doxygen style comment.
Struct members MUST be commented with a doxygen style comment.
Structs MUST be declared as typedefs.
Struct names MUST be all uppercase with underscores
(_)
between each word starting with the module prefix and ending with the suffix_s
.Struct members MUST be named as ordinary variables.
Anonymous structs MUST NOT be used, instead the struct type without the suffix
_s
MUST be defined.A trailing comma MUST be used after the last member.
A doxygen comment describing each struct MUST be added above the definition.
A doxygen comment describing each struct member MUST be added after the member.
Example:
1#include "general.h"
2
3/** Symbolic names for battery system state */
4typedef struct ABC_DATE {
5 uint16_t year; /*!< year */
6 uint8_t month; /*!< month (1: january ... 12: december) */
7 uint8_t day; /*!< day of the month */
8} ABC_DATE_s;
2.2.24. Enums (C:023
)
Enum rules
Enums MUST be commented with a doxygen style comment.
Enum members MUST be commented with a doxygen style comment.
Enums MUST be declared as typedefs.
Enums MUST be named all uppercase with underscores
(_)
between each word starting with the module prefix and ending with suffix_e
.Anonymous enums MUST NOT be used, instead the enum type without the suffix
_e
MUST be defined.Values MUST NOT be assigned to specific enum members.
Members MUST be named all in uppercase beginning with the module prefix.
No trailing comma MUST be used after the last entry.
The last member MUST be named after the typedef struct replacing the
_e
with_E
and appending the suffix_MAX
.A doxygen comment describing each enum MUST be added above the definition.
A doxygen comment describing each enum member MUST be added after the member.
1/** Symbolic names for weekdays */
2typedef enum ABC_DAYS {
3 ABC_MONDAY, /**< First day of the week */
4 ABC_TUESDAY, /**< Second day of the week */
5 /* ... */ /* more members */
6 ABC_SUNDAY, /**< Last day of the week */
7 ABC_DAYS_E_MAX /**< Max marker */
8} ABC_DAYS_e;
2.2.25. Typedefs (C:024
)
Typedef general rules
Typedef names MUST be all uppercase with underscores
(_)
between each word.Other typedef names MUST end with the suffix
_t
.
1#include "general.h"
2
3/* Remapping of types */
4typedef uint8_t mySpecialType;
5typedef uint32_t TICK_TYPE_t;
6
7mySpecialType a = 0;
8
9/* Using typedefs for the creation of function pointers */
10/* Pointer to functions with uint32_t return datatype and two function parameters of type uint32_t */
11typedef uint32_t (*CALLBACK_FUNCTION_POINTER_t)(uint32_t, uint32_t);
12
13/* Example */
14static uint32_t ABC_BuildSum(uint32_t varA, uint32_t varB); /* Function prototype */
15
16/* implement the prototype so that we have valid code */
17static uint32_t ABC_BuildSum(uint32_t varA, uint32_t varB) {
18 /* just an example: */
19 return varA + varB;
20}
21
22/* local variable of type callback_funcPtr_t */
23CALLBACK_FUNCTION_POINTER_t callback = &ABC_BuildSum;
24
25/* call of function ABC_BuildSum()*/
26void ABC_CallTheCallback(void) {
27 uint32_t temp = callback(37u, 42u);
28}
2.2.26. Macros (C:025
)
Macro rules
Macro names MUST be capitalized with underscores.
Macros MUST start with the module prefix.
If macros define a physical value, the name MUST be suffixed with the SI-unit or a SI-derived unit, e.g., use
F
for a capacity instead of SI unitss4_A2__m2_kg_1
.If macros are used to define a value, this value MUST be put in parentheses.
It is NOT RECOMMENDED to use function-like macros.
1#define ABC_GET_MINIMUM_FLOAT(x, y) DEF_CalculateMinimumFloat(x, y)
2#define ABC_PI_ROUNDED (3.14f)
3#define ABC_NUMBER_OF_DAYS_IN_A_WEEK (7u)
4#define ABC_MAXIMUM_PACK_VOLTAGE_mV (320000u)
5
6static float DEF_CalculateMinimumFloat(float x, float y);
7
8static float DEF_CalculateMinimumFloat(float x, float y) {
9 return 0.0f;
10}
2.2.27. Conditionals (C:026
)
Conditionals rules
No spaces MUST be used between the parentheses and the condition statement.
The
if
andelse
keywords MUST be placed in separate lines.A space between the
if
keyword and the open parenthesis and between the close parenthesis and the curly bracket MUST be placed.Multiple statements in one condition MUST be placed into separate parentheses. If you have a boolean expression that is longer than the standard line length, the logical operator MUST be at the end of the lines.
1#include "general.h"
2
3uint8_t condition = 0;
4uint8_t other_condition = 0;
5uint8_t this_one_thing = 0;
6uint8_t this_other_thing = 0;
7uint8_t a_third_thing = 0;
8uint8_t a_fourth_thing = 0;
9uint8_t yet_another = 0;
10uint8_t last_one = 0;
11
12void ABC_ConditionalFunction(void) {
13 if (condition) { /* no spaces inside parentheses */
14 /* code */ /* 4 space indent. */
15 } else if (other_condition) { /* The else if goes on the same line as the closing brace. */
16 /* code */ /* 4 space indent. */
17 } else { /* The else if goes on the same line as the closing brace. */
18 /* code */ /* 4 space indent. */
19 }
20 if ((this_one_thing > this_other_thing) && (a_third_thing == a_fourth_thing) && (yet_another && last_one)) {
21 /* code */
22 }
23}
2.2.28. switch Statements (C:027
)
Switch statement rules
Switch statements MUST use parentheses for blocks.
Fall-throughs between cases SHOULD NOT be used but instead all cases are terminated with one single break-statement at the end of the case. The only exceptions for this rules are empty fall-throughs that MUST be treated within the next case. These deliberate fall-throughs MUST be annotated.
Case blocks in switch statements MUST NOT use brackets.
Furthermore, switch statements MUST have a default case.
If the default case should never be executed, this MUST be treated as an error.
There MUST be an empty line between
break
and the nextcase
directive.
1#include "fassert.h"
2
3extern void ABC_SwitchFunction(uint8_t var) {
4 switch (var) {
5 case 0: /* 4 space indent */
6 /* code */ /* 4 space indent */
7 break;
8
9 case 1:
10 /* code */ /* 4 space indent */
11 break;
12
13 case 2:
14 /* code */ /* 4 space indent */
15 break;
16
17 case 3: /* Empty fall-through allowed as case 3 and 4 require the same treatment */
18 case 4:
19 /* case 3 and case 4 trigger the same response */
20 /* code */
21 break;
22
23 default:
24 FAS_ASSERT(FAS_TRAP);
25 break;
26 }
27}
2.2.29. loop Statements (C:028
)
loop rules
Parentheses MUST be used for all loops, at all times. This is valid for single-statement loops.
Empty loop bodies MUST use an empty pair of brackets and explain why they are empty.
1#include "general.h"
2
3static void C28_ForLoop(uint8_t kSomeNumber);
4static void C28_While(uint8_t condition);
5
6static void C28_ForLoop(uint8_t kSomeNumber) {
7 for (uint8_t i = 0u; i < kSomeNumber; ++i) {
8 /* code */
9 }
10}
11
12static void C28_While(uint8_t condition) {
13 while (condition) {
14 /* This should never happen, since ... */
15 }
16}
There are three defines that are typically looped over: the number of strings
(BS_NR_OF_STRINGS
), the number of modules (BS_NR_OF_MODULES
) and the
number of batteries per module (BS_NR_OF_CELLS_PER_MODULE
).
These loops MUST follow the pattern as shown in Table 2.13 and Listing 2.32.
Define |
Counter variable |
---|---|
|
|
|
|
|
|
1#include "battery_system_cfg.h"
2
3static void C28_BatteriesLoop(void);
4
5static void C28_BatteriesLoop(void) {
6 for (uint8_t s = 0u; s < BS_NR_OF_STRINGS; s++) {
7 /* string related code */
8 for (uint8_t m = 0u; m < BS_NR_OF_MODULES; m++) {
9 /* module related code */
10 for (uint8_t c = 0u; c < BS_NR_OF_CELLS_PER_MODULE; c++) {
11 /* cell related code */
12 }
13 }
14 }
15}
2.2.30. C Comment style (C:029
)
2.2.31. General note and common mistakes (C:030
)
For both, camel Case and Pascal Case, the general rules of the English
language apply.
This means that the correct version for a variable about the cell voltage is
abc_cellVoltage
(not abc_cellvoltage
).
2.2.32. C Formatting (C:031
)
Formatting
All code MUST be formatted according to the rules in this guidelines document.
Formatting SHOULD be done automatically by a tool.
2.2.33. State machines (C:032
)
If a driver (or similar) requires to be implemented in a state machine there are some hints found in How to Write State Machines.
2.2.34. File Templates
These file templates below show how these rules are correctly applied. They SHOULD be used as basis for new files.
2.2.34.1. C Header Files
1/**
2 *
3 * @copyright © 2010 - 2021, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
4 * All rights reserved.
5 *
6 * SPDX-License-Identifier: BSD-3-Clause
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright notice, this
12 * list of conditions and the following disclaimer.
13 *
14 * 2. Redistributions in binary form must reproduce the above copyright notice,
15 * this list of conditions and the following disclaimer in the documentation
16 * and/or other materials provided with the distribution.
17 *
18 * 3. Neither the name of the copyright holder nor the names of its
19 * contributors may be used to endorse or promote products derived from
20 * this software without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 *
33 * We kindly request you to use one or more of the following phrases to refer to
34 * foxBMS in your hardware, software, documentation or advertising materials:
35 *
36 * - ″This product uses parts of foxBMS®″
37 * - ″This product includes parts of foxBMS®″
38 * - ″This product is derived from foxBMS®″
39 *
40 */
41
42/**
43 * @file c.h
44 * @author foxBMS Team
45 * @date 2019-08-27 (date of creation)
46 * @updated 2020-08-10 (date of last update)
47 * @ingroup SOME_GROUP
48 * @prefix ABC
49 *
50 * @brief Header file of some software
51 *
52 */
53
54#ifndef FOXBMS__C_H_
55#define FOXBMS__C_H_
56
57/*========== Includes =======================================================*/
58
59/*========== Macros and Definitions =========================================*/
60
61/*========== Extern Constant and Variable Declarations ======================*/
62
63/*========== Extern Function Prototypes =====================================*/
64
65/*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
66
67#endif /* FOXBMS__C_H_ */
2.2.34.2. C Source Files
1/**
2 *
3 * @copyright © 2010 - 2021, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
4 * All rights reserved.
5 *
6 * SPDX-License-Identifier: BSD-3-Clause
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright notice, this
12 * list of conditions and the following disclaimer.
13 *
14 * 2. Redistributions in binary form must reproduce the above copyright notice,
15 * this list of conditions and the following disclaimer in the documentation
16 * and/or other materials provided with the distribution.
17 *
18 * 3. Neither the name of the copyright holder nor the names of its
19 * contributors may be used to endorse or promote products derived from
20 * this software without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 *
33 * We kindly request you to use one or more of the following phrases to refer to
34 * foxBMS in your hardware, software, documentation or advertising materials:
35 *
36 * - ″This product uses parts of foxBMS®″
37 * - ″This product includes parts of foxBMS®″
38 * - ″This product is derived from foxBMS®″
39 *
40 */
41
42/**
43 * @file c.c
44 * @author foxBMS Team
45 * @date 2019-08-27 (date of creation)
46 * @updated 2020-08-10 (date of last update)
47 * @ingroup SOME_GROUP
48 * @prefix ABC
49 *
50 * @brief Implementation of some software
51 *
52 */
53
54/*========== Includes =======================================================*/
55#include "c.h"
56
57/*========== Macros and Definitions =========================================*/
58
59/*========== Static Constant and Variable Definitions =======================*/
60
61/*========== Extern Constant and Variable Definitions =======================*/
62
63/*========== Static Function Prototypes =====================================*/
64
65/*========== Static Function Implementations ================================*/
66
67/*========== Extern Function Implementations ================================*/
68
69/*========== Externalized Static Function Implementations (Unit Test) =======*/
2.2.34.3. C Test Header Files
1/**
2 *
3 * @copyright © 2010 - 2021, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
4 * All rights reserved.
5 *
6 * SPDX-License-Identifier: BSD-3-Clause
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright notice, this
12 * list of conditions and the following disclaimer.
13 *
14 * 2. Redistributions in binary form must reproduce the above copyright notice,
15 * this list of conditions and the following disclaimer in the documentation
16 * and/or other materials provided with the distribution.
17 *
18 * 3. Neither the name of the copyright holder nor the names of its
19 * contributors may be used to endorse or promote products derived from
20 * this software without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 *
33 * We kindly request you to use one or more of the following phrases to refer to
34 * foxBMS in your hardware, software, documentation or advertising materials:
35 *
36 * - ″This product uses parts of foxBMS®″
37 * - ″This product includes parts of foxBMS®″
38 * - ″This product is derived from foxBMS®″
39 *
40 */
41
42/**
43 * @file test_c.h
44 * @author foxBMS Team
45 * @date 2020-08-10 (date of creation)
46 * @updated 2020-08-10 (date of last update)
47 * @ingroup UNIT_TEST_IMPLEMENTATION
48 * @prefix TEST
49 *
50 * @brief Test header of the some module
51 *
52 */
53
54#ifndef FOXBMS__TEST_C_H_
55#define FOXBMS__TEST_C_H_
56
57/*========== Includes =======================================================*/
58
59/*========== Macros and Definitions =========================================*/
60
61#endif /* FOXBMS__TEST_C_H_ */
2.2.34.4. C Test Source Files
1/**
2 *
3 * @copyright © 2010 - 2021, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
4 * All rights reserved.
5 *
6 * SPDX-License-Identifier: BSD-3-Clause
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright notice, this
12 * list of conditions and the following disclaimer.
13 *
14 * 2. Redistributions in binary form must reproduce the above copyright notice,
15 * this list of conditions and the following disclaimer in the documentation
16 * and/or other materials provided with the distribution.
17 *
18 * 3. Neither the name of the copyright holder nor the names of its
19 * contributors may be used to endorse or promote products derived from
20 * this software without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 *
33 * We kindly request you to use one or more of the following phrases to refer to
34 * foxBMS in your hardware, software, documentation or advertising materials:
35 *
36 * - ″This product uses parts of foxBMS®″
37 * - ″This product includes parts of foxBMS®″
38 * - ″This product is derived from foxBMS®″
39 *
40 */
41
42/**
43 * @file test_c.c
44 * @author foxBMS Team
45 * @date 2020-08-10 (date of creation)
46 * @updated 2020-08-10 (date of last update)
47 * @ingroup UNIT_TEST_IMPLEMENTATION
48 * @prefix TEST
49 *
50 * @brief Test of some module
51 *
52 */
53
54/*========== Includes =======================================================*/
55#include "unity.h"
56
57/*========== Definitions and Implementations for Unit Test ==================*/
58
59/*========== Setup and Teardown =============================================*/
60void setUp(void) {
61}
62
63void tearDown(void) {
64}
65
66/*========== Test Cases =====================================================*/
Comment Style
Only ANSI-C comments MUST be used (
/* */
).Comments MUST NOT be nested.