Code style

Roughly Linux kernel code style (its ASCII source is here)

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
• Casts are NOT followed by a space (e.g. (int *)malloc(4)).
• Typedefs are OK, use *_t notation
• Prefixed #ifdefs (#ifdef _KNOTD_FOOBAR)
  • Instead of header guard like KNOTD_HEADER_H we use #pragma once
• #endif followed by comment specifying corresponding #ifdef (#endif /* KNOTD_FOOBAR */ )
• 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
• Includes in each group shall be sorted alphabetically by their full paths (with necessary functional exceptions such as <sys/.h> and <net/.h> first in BSD's).
• 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

/*!
 * \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()
{
...
}

/*! @} */