Comment

Comments are the way programmers explain parts of their code.

They act as guides to future maintainers as to how the codebase is structured.

What comments should do

Comments are very useful when:

• You have a complicated piece of code and its function can be explained simply in a comment (often though, it makes more sense to create a function for this).
• You've found that the current implementation is faster, and want to explain that to future maintainers
• Credit code from other sources
• Provide links to further reading on a concept
• Use doc comments for documenting a function, struct field, etc.

What comments should NOT do

• Explain what the code is doing - e.g. redundant comments explaining why if age < 18 checks if age is less than 18.
• Explaining an if statement, switch statement or other condition - usually, this indicates you should create a constant for any magic numbers in your condition, or extract out parts of your condition into separate (boolean) variables.
• Commenting out code: this is ok in your dev branch, but should never be in production.
• Document the changes to code: use a changelog for this!

Example of a C-style single line comment

// this is a full-line C-style comment
int a = 5; // you can also place them at the end of a statement

Example of a C-style multi line comment

/*
This is a multi-line comment
They start with a / then a * ...
... and end with a * then a /
*/

/* it's often convention to start each new line in
 * a multi-line comment with an asterisk (*) to
 * maintain formatting. */