.. include:: ./../../macros.txt .. include:: ./../../units.txt .. _C_CODING_GUIDELINES: 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 ``pre-commit`` check before files can be merged into the master branch of the repository. Generally |foxbms| uses for the embedded code `1TBS `_. This is checked by ``clang-format``. The ``clang-format`` configuration is found in the root of the repository in ``.clang-format``. Directories that should not be automatically formatted must include a ``.clang-format`` file to disable automatic formatting: .. code-block:: yaml DisableFormat: true SortIncludes: false The ``C`` source and header files can be checked by running ``pre-commit``. Using VS Code files are automatically saved correctly (see :ref:`CREATING_A_WORKSPACE`) when ``clang-format`` is installed (see :ref:`software_prerequisites`) using :kbd:`Ctrl-S`. .. warning:: The style of third party sources (generated HAL sources in ``build/app_embedded/src/app/hal/**`` and ``src/os``) should not be changed. To save without reformatting use :kbd:`Ctrl-K + Ctrl-Shift-S`. The following list shows more detailed rules for |foxbms|. 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 pattern ``C:``. .. _rule_c_filenames: Filenames (``C:001``) --------------------- Additional to the general file naming rules the following **MUST** be applied. .. admonition:: File name rules - The general file naming rules **MUST** be applied (see :numref:`rule_general_filenames`). - ``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`` .. _rule_c_header: Header (``C:002``) ------------------ .. admonition:: C file header C source and header files **MUST** start with the following header: .. literalinclude:: ./../../../conf/tpl/c.c :language: C :linenos: :lines: 1-40 :caption: File header for all ``.c`` and ``.h`` files. :name: file-header-c-and-h .. _rule_c_line_length: Line length (``C:003``) ----------------------- .. admonition:: Line length 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. .. _rule_c_file_level_doxygen: File level doxygen (``C:004``) ------------------------------ `Doxygen `_ is used to create an API documentation. .. admonition:: 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)``. :numref:`doxygen-test-c` shows how this looks for a file ``c-004.c``. .. literalinclude:: ./examples/c-004.c :language: C :lines: 41-53 :linenos: :emphasize-lines: 2-8,10,11 :caption: File level doxygen for c-004.c :name: doxygen-test-c .. _rule_c_include_guard: 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. .. admonition:: 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``. :numref:`include-guard-c-005-h` shows how this looks for a file ``c-005.h``, where the include guard would be ``FOXBMS__C_005_H_``. .. literalinclude:: ./examples/c-005.h :language: C :lines: 55,56,70 :linenos: :emphasize-lines: 1,2,3 :caption: Include guard for ``c-005.h`` :name: include-guard-c-005-h .. _rule_c_sections: C Sections (``C:006``) ---------------------- .. admonition:: 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/**``). :numref:`c_section_header` shows how this looks for a file ``c-006-source.h``. .. literalinclude:: ./examples/c-006-source.h :language: C :lines: 58-66 :linenos: :emphasize-lines: 1,3,5,7,9 :caption: section markers for ``c-006-source.h`` :name: c_section_header :numref:`c_section_source` shows how this looks for a file ``c-006-source.c``. .. literalinclude:: ./examples/c-006-source.c :language: C :lines: 55-69 :linenos: :emphasize-lines: 1,3,5,7,9,11,13,15 :caption: section markers for ``c-006-source.c`` :name: c_section_source :numref:`c_section_test_header` shows how this looks for a file ``./test/c-006-test.h``. .. literalinclude:: ./examples/c-006-test.h :language: C :lines: 58-62 :linenos: :emphasize-lines: 1,3,5 :caption: section markers for ``./test/c-006-test.h`` :name: c_section_test_header :numref:`c_section_test_source` shows how this looks for a file ``./test/c-006-test.c``. .. literalinclude:: ./examples/c-006-test.c :language: C :lines: 58-66 :linenos: :emphasize-lines: 1,3,5,7,9 :caption: section markers for ``./test/c-006-test.c`` :name: c_section_test_source .. _rule_c_includes: 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. .. admonition:: Include rules - All includes **MUST** be listed after the ``includes`` marker. - |foxbms| uses the `include-what-you-use `_ paradigm. - Only required includes **MUST** be added. - Forward declarations **MUST NOT** be used. Instead, you **MUST** ``#include`` all the headers that declare functions, types etc. you need. - Configuration header files **MUST** apply the following order of includes: #. Include ``general.h``, if needed #. A blank line #. Add required includes in alphabetical order according to rule - Other header files **MUST** apply the following order of includes: #. Include ``general.h``, if needed #. Include corresponding configuration header if it exists #. 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 only**) #. A blank line #. Generated Mock-header (**for unit tests only**) #. A blank line #. Any ``*_cfg.h`` that is included #. A blank line #. HAL-headers starting with ``HL_``-header files and ending with ``ti_``-header files #. A blank line #. |freertos| headers starting with ``FreeRTOS.h`` #. A blank line #. All other required headers except Mocks :numref:`includes-c-007_abc_cfg-h`, :numref:`includes-c-007_abc_cfg-c`, :numref:`includes-c-007_abc-h` and :numref:`includes-c-007_abc-c` show how includes **MUST** be added. .. literalinclude:: ./examples/c-007_abc_cfg.h :language: C :lines: 59,60 :linenos: :caption: Include order for ``c-007_abc_cfg.h`` :name: includes-c-007_abc_cfg-h .. literalinclude:: ./examples/c-007_abc_cfg.c :language: C :lines: 56-59 :linenos: :caption: Include order for ``c-007_abc_cfg.c`` :name: includes-c-007_abc_cfg-c .. literalinclude:: ./examples/c-007_abc.h :language: C :lines: 59-62 :linenos: :caption: Include order for ``c-007_abc.h`` :name: includes-c-007_abc-h .. literalinclude:: ./examples/c-007_abc.c :language: C :lines: 56-63 :linenos: :caption: Include order for ``c-007_abc.c`` :name: includes-c-007_abc-c .. _rule_c_scoping: Scoping (``C:008``) ------------------- .. admonition:: 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. .. literalinclude:: ./examples/c-008.c :language: C :lines: 63-80 :linenos: :caption: Narrowest variable scope :name: narrowest-variable-scope .. _rule_c_function_names: Function names (``C:009``) -------------------------- .. admonition:: 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 :ref:`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. :numref:`function-names`, shows correctly named functions. .. literalinclude:: ./examples/c-009.c :language: C :lines: 64-65,68-71 :linenos: :caption: Function names using the uppercase module prefix. :name: function-names .. _rule_c_function_scopes: Function scopes (``C:010``) --------------------------- .. admonition:: Function scope rules - Global and static functions **MUST** be declared respectively with the keywords ``extern`` or ``static``. 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. :numref:`function-prototype-and-doxygen` and :numref:`function-implementation-and-doxygen` show correctly declared and implemented functions on the header ``abc.h`` and respective source file ``abc.c``. .. _rule_c_function_doxygen_documentation: Function doxygen documentation (``C:011``) ------------------------------------------ .. admonition:: 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 type ``void``. - Function arguments **MUST** be documented using the doxygen parameter ``@param``. - If a function argument is a pointer, the data flow direction (indicating if the pointer is used as input, output or both) **MUST** be indicated with a suffixed ``[in]``, ``[out]`` or ``[in,out]`` after the ``@param`` tag. - This practice **MUST NOT** be applied to normal parameters that are passed by value as they are implicitly assumed to be input. - All doxygen parameter arguments **MUST** be whitespace aligned. :numref:`function-prototype-and-doxygen` and :numref:`function-implementation-and-doxygen` show doxygen documented functions in a header file ``c-011.h`` and source file ``c-011.c``. .. literalinclude:: ./examples/c-011.h :language: C :lines: 66-73 :linenos: :caption: Global function declaration in ``c-011.h`` and its doxygen comment :name: function-prototype-and-doxygen .. literalinclude:: ./examples/c-011.c :language: C :lines: 67-84 :linenos: :caption: Static and global functions in ``c-011.c`` ant their doxygen comments :name: function-implementation-and-doxygen .. _rule_c_function_return_value: Function return statement (``C:012``) ------------------------------------- .. admonition:: 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. :numref:`return-parentheses-usage` shows how to correctly use parentheses and the return statement. .. literalinclude:: ./examples/c-012.c :language: C :lines: 70-73,75-82 :linenos: :emphasize-lines: 3,7-11 :caption: Correct usage of the ``return`` statement. :name: return-parentheses-usage .. _rule_c_function_calls: Function calls (``C:013``) -------------------------- .. admonition:: 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 :numref:`function-call`. .. literalinclude:: ./examples/c-013.c :language: C :lines: 78-83,87-93,96-98,100-120 :linenos: :emphasize-lines: 3-5,9-11,25-29,32-34 :caption: Correct formatting of function calls. :name: function-call .. _rule_c_additional_function_rules: 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. .. admonition:: 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) .. _rule_c_function_parameter_checking: Function parameter checking (``C:015``) --------------------------------------- .. admonition:: 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``. - The check **SHOULD** be implemented with an assertion. - If no assertion can be made for the parameter (e.g., if the parameter intentionally accepts all possible values), the parameter **MUST** be marked like this at the start of the function context: ``/* AXIVION Routine Generic-MissingParameterAssert: *ENTITY_NAME*: *RATIONALE* */``. Parameter checking is shown in :numref:`function-input-check`. .. literalinclude:: ./examples/c-015.c :language: C :lines: 74-89 :linenos: :emphasize-lines: 2,3,4 :caption: Input check of function parameters :name: function-input-check .. _rule_c_variable_names: Variable names (``C:016``) -------------------------- .. admonition:: 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 ``_`` (e.g., ``_mA`` for milliampere or ``K`` for Kelvin). Exceptions are non-ASCII symbols as - ``_perc`` for ``%``, - ``_degC`` for ``°C`` and - ``u`` for ``μ``. - A doxygen comment explaining what this variable is used for **MUST** be added to all static and global variables. .. literalinclude:: ./examples/c-016.c :language: C :lines: 62-63,66,73,74,78 :linenos: :caption: Different examples for correctly named variables and functions. .. _rule_c_constant_names: Constant names (``C:017``) -------------------------- .. admonition:: 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. .. literalinclude:: ./examples/c-017.c :language: C :lines: 62 :linenos: :caption: Correct examples for naming constant variables. .. _rule_c_pointer_rules: Pointer rules (``C:018``) ------------------------- .. admonition:: Pointer rules - The general variable name rules apply (see :ref:`rule_c_variable_names`). - Variables used for pointers **MUST** be prefixed with a leading ``p`` in the case of a pointer to a variable and ``fp`` in the case of a function pointer, followed by camel Case. - The const rules also still apply to pointers (:ref:`rule_c_constant_names`), i.e., - for a const pointer the prefix is ``kp``, - for a pointer to a const the prefix is ``pk``, and - for a const pointer to a const the prefix is ``kpk``. - 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: .. literalinclude:: ./examples/c-018.c :language: C :lines: 61-65,68-70,73,74,80-85 :linenos: :caption: Correct usage of pointers. .. _rule_c_variable_initialization: Variable initialization (``C:019``) ----------------------------------- .. admonition:: 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 :numref:`table-variable-initialization` for details. - Pointers **MUST** be initialized with ``NULL_PTR`` if no other valid initialization is possible. .. _table-init-rules: .. table:: Variable initialization suffixes :name: table-variable-initialization +----------+----------+ | Type | Suffix | +==========+==========+ | uint8_t | ``u`` | +----------+----------+ | uint16_t | ``u`` | +----------+----------+ | uint32_t | ``u`` | +----------+----------+ | uint64_t | ``uLL`` | +----------+----------+ | int8_t | ``none`` | +----------+----------+ | int16_t | ``none`` | +----------+----------+ | int32_t | ``none`` | +----------+----------+ | int64_t | ``LL`` | +----------+----------+ .. literalinclude:: ./examples/c-019.c :language: C :lines: 60-72,78-106 :linenos: :caption: Initialization examples for variables and complex types .. _rule_c_hexadecimal: Hexadecimal values (``C:020``) ------------------------------ .. admonition:: Hexadecimal values rules Hexadecimal digits **MUST** be written in uppercase letters. .. literalinclude:: ./examples/c-020.c :language: C :lines: 64,65 :linenos: :caption: Correct usage of hexadecimal digits. .. _rule_c_floating_point: Floating-point values (``C:021``) --------------------------------- .. admonition:: 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. .. _table-floating-point-init-rules: .. table:: Floating-point literal initialization suffixes :name: table-floating-point-initialization +----------+----------+ | Type | Suffix | +==========+==========+ | float_t | ``f`` | +----------+----------+ | double | ``none`` | +----------+----------+ .. literalinclude:: ./examples/c-021.c :language: C :lines: 62-65 :linenos: :caption: Usage of floating-point literals. .. _rule_c_structs: Structs (``C:022``) ------------------- .. admonition:: 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: .. literalinclude:: ./examples/c-022.c :language: C :lines: 60-65 :linenos: :caption: Correct struct implementation. .. _rule_c_enums: Enums (``C:023``) ----------------- .. admonition:: 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. .. literalinclude:: ./examples/c-023.c :language: C :lines: 60-67 :linenos: :caption: Correct enum implementation. .. _rule_c_typedefs: Typedefs (``C:024``) -------------------- .. admonition:: Typedef general rules - Typedef names **MUST** be all uppercase with underscores ``(_)`` between each word. - Other typedef names **MUST** end with the suffix ``_t``. .. literalinclude:: ./examples/c-024.c :language: C :lines: 59,91 :linenos: :caption: Correct example for usage of typedefs. .. _rule_c_macros: Macros (``C:025``) ------------------ .. admonition:: 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 units ``s4_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. .. literalinclude:: ./examples/c-025.c :language: C :lines: 58-61 :linenos: :caption: Correct naming examples of macros. .. _rule_c_conditionals: Conditionals (``C:026``) ------------------------ .. admonition:: Conditionals rules - No spaces **MUST** be used between the parentheses and the condition statement. - The ``if`` and ``else`` 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. .. literalinclude:: ./examples/c-026.c :language: C :lines: 61-69,78-90 :linenos: :caption: Correct implementation of if-else statements. .. _rule_c_switch: switch Statements (``C:027``) ----------------------------- .. admonition:: 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 next ``case`` directive. .. literalinclude:: ./examples/c-027.c :language: C :lines: 69-93 :linenos: :caption: Correct implementation of switch-case statement. .. _rule_c_loop: loop Statements (``C:028``) ----------------------------- .. admonition:: 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. .. literalinclude:: ./examples/c-028.c :language: C :lines: 70-80 :linenos: :caption: Correct usage of spaces and parentheses in loop statements. 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_PER_STRING``) and the number of batteries per module (``BS_NR_OF_CELL_BLOCKS_PER_MODULE``). These loops **MUST** follow the pattern as shown in :numref:`special-counter-variables` and :numref:`special-counter-variables-example`. .. table:: Special counter variables in for loops :name: special-counter-variables :widths: grid +--------------------------------------+-------------------+ | Define | Counter variable | +======================================+===================+ | ``BS_NR_OF_STRINGS`` | ``s`` | +--------------------------------------+-------------------+ | ``BS_NR_OF_MODULES_PER_STRING`` | ``m`` | +--------------------------------------+-------------------+ | ``BS_NR_OF_CELL_BLOCKS_PER_MODULE`` | ``cb`` | +--------------------------------------+-------------------+ | ``BS_NR_OF_TEMP_SENSORS_PER_MODULE`` | ``ts`` | +--------------------------------------+-------------------+ .. literalinclude:: ./examples/c-028-battery-defines.c :language: C :lines: 41- :linenos: :caption: Looping over ``BS_NR_OF_STRINGS``, ``BS_NR_OF_MODULES_PER_STRING`` and ``BS_NR_OF_CELL_BLOCKS_PER_MODULE`` :name: special-counter-variables-example .. _rule_c_comment_style: C Comment style (``C:029``) --------------------------- .. admonition:: Comment Style - Only ANSI-C comments **MUST** be used (``/* */``). - Comments **MUST NOT** be nested. .. _rule_c_hints: 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``). .. _rule_c_formatting: C Formatting (``C:031``) ------------------------ .. admonition:: Formatting - All code **MUST** be formatted according to the rules in this guidelines document. - Formatting **SHOULD** be done automatically by a tool. .. _rule_c_state_machines: State machines (``C:032``) -------------------------- If a driver (or similar) requires to be implemented in a state machine there are some hints found in :ref:`HOW_TO_WRITE_STATE_MACHINES`. .. _rule_c_unit_testing_framework_directives: Unit Testing Framework Directives (``C:033``) --------------------------------------------- If a driver (or similar) requires to be implemented in a state machine there are some hints found in :ref:`HOW_TO_WRITE_STATE_MACHINES`. File Templates -------------- These file templates below show how these rules are correctly applied. They **SHOULD** be used as basis for new files. - C header file :download:`c.h <../../../conf/tpl/c.h>` - C source file :download:`c.c <../../../conf/tpl/c.c>` - C test header file :download:`test_c.h <../../../conf/tpl/test_c.h>` - C test source file :download:`test_c.c <../../../conf/tpl/test_c.c>` C Header Files ^^^^^^^^^^^^^^ .. literalinclude:: ../../../conf/tpl/c.h :language: C :linenos: :caption: File template for C header files :name: c-h-template C Source Files ^^^^^^^^^^^^^^ .. literalinclude:: ../../../conf/tpl/c.c :language: C :linenos: :caption: File template for C source files :name: c-c-template C Test Header Files ^^^^^^^^^^^^^^^^^^^ .. literalinclude:: ../../../conf/tpl/test_c.h :language: C :linenos: :caption: File template for C test header files :name: test-c-h-template C Test Source Files ^^^^^^^^^^^^^^^^^^^ .. literalinclude:: ../../../conf/tpl/test_c.c :language: C :linenos: :caption: File template for C test source files :name: test-c-c-template