comments.md

February 16, 2019 · View on GitHub

<<< Table of contents

Comments

Aim to comment your code properly.

Write both higher-level comments, as well as more detailed lower-level comments wherever appropriate. Any technically skilled colleague should be able to understand what is going on from both code as well as comments. Start-up costs related to code understanding should be kept to a minimum by commenting judiciously.
On the other hand, do not bury your code in comments. Omit any obvious comments (++i; // increments i). Well-written code should be largely self-documenting through choice of good variable and function names, logical program flows, etc.
All comments should be written in C++-style (//), with a variant of the C-style (/*) being mainly reserved for Doxygen-style documentation (/**).

Always follow with a whitespace after starting a comment.

Example:
```
// This is a proper comment.
//Do not omit the whitespace.
```
```
/* Don’t write cumbersome C-style comments either. */
```
```
/**
 * @brief It’s ok and even encouraged for Doxygen-style documentation.
 */
```
```
/// This is also Doxygen-style documentation.
```
- C-style comments can not be nested; C++-style comments can be (per line), and many IDEs support automatic commenting or uncommenting of code blocks.
When providing Doxygen-style documentation, place it directly above the definition of a function/member function, not the initial declaration either inside or outside of a class.
- Doxygen-style documentation is meant to be read in a browser, not inside the code. Any reader of your class should be able to get a quick overview by looking at the public interface in-code, and the more of the class fits onto a screen, the easier it is to read. Do not blow up the size of your class definitions by providing in-line documentation. Also, this is one more reason to cleanly separate function declaration from definition (see also below, in ‘Classes’ section).

<<< Table of contents