Documentation

Though your code should be relatively self-documenting, at least document all of your complex functions. Jumping into a well documented application codebase and library is helpful and appreciated, especially when the flow isn't obvious!

System

Use Doxygen for header documentation.

For implementation documentation, use the basic language comments to explain a complex or non-obvious piece of code.

Style

Use two asterisks to delineate the beginning of a class, function, method or variable comment.

Rules

  • Only one space must follow the /**.
  • The initial sentence must be a summary of the intent, or a well described intent in and of itself.
  • This summary must be written in normal sentence case and end with a period.
  • The summary must be written on the same line as the /**.
  • If the comment is easy to read on one line, put it on one line!
  • Otherwise, if the comment spans multiple lines, the closing */ must be on its own line.
  • Use simple newlines for separator lines.
  • Do not use a symbol to represent the beginning of a new line!
  • Use the @ symbol for commands.
/** Does stuff and things.
 
    This function is very important for... reasons.
*/
void foo();
/** A double-precision floating point representation of pi.
 
    @see https://en.wikipedia.org/wiki/Pi
*/
static const double pi = 3.141592654;
/** @see https://www.google.ca */
void bar();

Command Rules

Do not redundantly specify default commands.

For example, do this to automatically make use of @brief and @details:

/** Does stuff and things
 
    Does an important bunch of stuff and things.
*/
void foo();

Do not specify the following commands, unless there's something legal telling you otherwise (or use your best judgement!):

Try to limit to using these commands in your code:

  • @internal
    • Only when overriding a method.
  • @code and @endcode to show examples.
  • @param to describe parameters.
  • @param[out] to describe outputted parameters.
    • For consistency, do not use @param[in] to describe inputted parameters.
    • Not using @param[in] helps the eye more easily catch the out of the ordinary @param[out] specifier.
  • @return or @returns to describe the purpose behind the returned value or object.
  • @see
    • To point to other pieces code, like methods or variables.
    • To point to web URLs.
  • @bug
  • @warning