Guidelines for C++ code comments

There are two types of code comments for C++ files: doxygen style and C++ style comments.

• Doxygen styled comments are used for describing things like the purpose of the function, which parameters it accepts, and what output it generates.

• Use Doxygen style comments in the header (.h) files. Avoid using them in .cpp files.

• Do not duplicate code in comments.

Generate HTML from doxygen comments

To generate HTML output of the doxgyen comments,

in the build directory,

run cmake with developer documentation on:

cmake -Dwith-devdoc=ON path/to/nest-simulator.

then

make docs
xdg-open doc/doxygen/html/index.html

See also

See the official doxygen documentation for details.

Doxygen style

• Multi-line comments

/**
 * Short description
 *
 * Further details, if necesary
 */

Note

Functions and classes should use the multi-line style even for single line comments.

• Single or two line comments to use with variables:

//! The maximum delay of the simulation
long may_delay;

• If a short comment is needed for variables, you can add a comment to the right of the code:

long max_delay_; //!< The maximum delay of the simulation

C++ style

• Multi-line comments:

 //
 //
 //
 //

* Single or two line comments:

//