The Allman style indentation is used.
All functions/variables/files/macros/typedefs/structs/unions etc should be documented. The main rule is that everything in the .h file is documented and everything in the .c file is documented (except for the things already documented in the .h) file. Function prototypes and other declarations are documented and not imports and implementations. No documentation should be added for stack allocated variables.
The use of redundant information and excessive tag usage should be avoided. See the following example of the documentation for a file:
/**
* @brief This is a brief description
*
* @details This is a detailed description of what this file does. This
* can be multi-line and multi-sentance.
*
* @file driver.c
*/
Using the correct settings for Doxygen the same can be accomplished using:
/**
* This is a brief description.
*
* This is a detailed description of what this file does. This
* can be multi-line and multi-sentance.
*
* @file
*/
The tags for Doxygen should use the @ and the comments should use the notation except for structs/enums/etc (see below):
/** Doxygen comment */
/**
* Doxygen comment.
* More comments
*/
The file header should follow this template:
/*
Insert license text here.
*/
/**
* This is the brief description.
*
* This is the detailed description. It is multi-line
* and multi-sentance.
*
* @file
*/
Functions should be documented according to the following:
/**
* This is the brief description.
*
* This is the detailed description. It can be multi-line and
* multi-sentance.
*
* @param[in] param1 Pass data into the function
* @param[out] param2 Pass buffer to put return data into
*
* @return Description of the return (omitted if void)
*/
The same style should be used for structs/enums/unions:
/** Struct for Testing */
typedef struct {
uint32_t var1; ///< Variable 1
uint32_t var2; ///< Variable 2
} TestStruct;
The following should be used for variables/typedef declarations.
/** Definition of U32 */
typedef uint32_t U32;
/** Variable for counting calls */
uint32_t calls;
/** Max count for things */
#define MAX_COUNT
/** Macro for selecting max value */
#define MAX(a,b) (a>b?a:b)
We aim to follow PEP-8 and PEP-257 as much as possible.
We aim to use the following name convention in our python code:
HighLevelCommander:)send_positioning())lh_v1_vert_angle)In the cflib we have a lot of legacy code that use different conventions, but all new code should use the one defined above
For documentation doc strings are used.
For static code analysis Flake8 and pylint are used. For pylint the following exceptions has been made: