|
|
# Code style
|
|
|
|
|
|
Roughly Linux kernel code style: https://www.kernel.org/doc/Documentation/CodingStyle
|
|
|
|
|
|
## Exceptions and clarifications
|
|
|
|
|
|
* Tabs for indentation, spaces otherwise (aligning comments, parameters on next line, etc.)
|
|
|
* E.g. when aligning wrapped line, use tabs to follow indents, then spaces to align
|
|
|
* Typedefs are OK, use *_t notation
|
|
|
* Prefixed #ifdefs (#ifdef <notextile>_KNOTD_FOOBAR</notextile>)
|
|
|
* Instead of header guard like <notextile>_KNOTD_HEADER_H_</notextile> we use #pragma once
|
|
|
* #endif followed by comment specifying corresponding #ifdef (#endif <notextile>/* _KNOTD_FOOBAR_ */</notextile> )
|
|
|
* Private functions (only in .c files) should always be @static@
|
|
|
* Order of includes (groups separated by one empty line)
|
|
|
* System libraries
|
|
|
* 3rd party libraries
|
|
|
* Corresponding header file
|
|
|
* Other header files from our project
|
|
|
* Comments & documentation:
|
|
|
* OK to use comments in function body (and they may describe how something is done)
|
|
|
* For doxygen comments see below
|
|
|
|
|
|
## Doxygen
|
|
|
|
|
|
* Format: Qt-style
|
|
|
* @\brief@, not @@brief@
|
|
|
* @/*!@, not @/**@
|
|
|
* Order of sections
|
|
|
* brief description
|
|
|
* long description
|
|
|
* notes
|
|
|
* warnings
|
|
|
* references
|
|
|
* parameters
|
|
|
* return values
|
|
|
* todos
|
|
|
* Always use @\brief@ (no autobrief)
|
|
|
* Indent text (using spaces only) in multiple-line sections
|
|
|
* In multi-line comments, opening line (@/*!@) should be empty
|
|
|
* One empty line between two consecutive sections
|
|
|
* Struct and union members documented on the same line if the comment fits
|
|
|
* Use @\retval@ (or more of them) instead of @\return@ if the function returns some distinct values (such as 0 for no error, -1 for something else, etc.)
|
|
|
* Every header file should have a file comment in form:
|
|
|
* file
|
|
|
* brief description
|
|
|
* long description
|
|
|
* notes
|
|
|
* warnings
|
|
|
* todos
|
|
|
* grouping
|
|
|
* Every API function should have a comment containing at least:
|
|
|
* brief description
|
|
|
* parameters (if applicable)
|
|
|
* return values (if applicable)
|
|
|
|
|
|
### Sample
|
|
|
|
|
|
```c
|
|
|
/*!
|
|
|
* \file
|
|
|
*
|
|
|
* \brief Contains some pretty fancy functions.
|
|
|
*
|
|
|
* These functions are very cool.
|
|
|
*
|
|
|
* \note Well, you shouldn't use them anyway as they are deprecated.
|
|
|
*
|
|
|
* \warning Do not use these functions!
|
|
|
*
|
|
|
* \todo Remove.
|
|
|
*
|
|
|
* \addtogroup mygroup
|
|
|
* @{
|
|
|
*/
|
|
|
|
|
|
#pragma once
|
|
|
|
|
|
/*!
|
|
|
* \brief Some structure.
|
|
|
*
|
|
|
* Longer description.
|
|
|
*/
|
|
|
struct some_struct {
|
|
|
/*!
|
|
|
* \brief This comment does not fit on the same line as the member
|
|
|
* as it is rather large.
|
|
|
*/
|
|
|
int fd;
|
|
|
int flags; /*!< Flags. */
|
|
|
};
|
|
|
|
|
|
|
|
|
/*!
|
|
|
* \brief Brief description of some function.
|
|
|
*
|
|
|
* Longer description.
|
|
|
*
|
|
|
* \note This function is deprecated.
|
|
|
*
|
|
|
* \warning Do not use this function!
|
|
|
*
|
|
|
* \see some_other_function()
|
|
|
*
|
|
|
* \param param1 Some parameter.
|
|
|
* \param param2 Other parameter. This one has rather large comment,
|
|
|
* so its next line is indented for better readability.
|
|
|
*
|
|
|
* \retval 0 on success.
|
|
|
* \retval -1 if some error occured.
|
|
|
*
|
|
|
* \todo Remove (deprecated).
|
|
|
*/
|
|
|
void some_function()
|
|
|
{
|
|
|
...
|
|
|
}
|
|
|
|
|
|
/*! @} */
|
|
|
``` |
|
|
\ No newline at end of file |