C/C++ Programming Style Guidelines

5.2. Content
End-line comments are acceptable for describing variable declarations. Use a comment
to describe any variable whose purpose is not obvious from its name.
Use comments to document your intent. Do not describe how your code works, that
should be obvious from the implementation. Instead describe why your code does what
it does. Avoid explaining especially tricky code in comments. Instead, rewrite the code
to make it intrinsically more obvious. Use complete sentences with proper spelling and
punctuation in all comments.
Write your comments before and as you write your code, not after. If you start by
writing comments you give yourself a low-level design for the implementation. When
you are finished testing your code, go back and review all comments to make sure they
are still accurate.
Comment things that have wide impact. If a function makes assumptions about the
condition of variable on input, document that. If a required speed optimization makes
the code difficult to read, explain the need for the code in a comment. If your code uses
or changes any global variables, comment that.
Use bold comments to delimit major sections in your code file. You may, for instance,
implement a number of private utility functions. Use a bold comment to mark the start
of that code. Preface each function with a block comment describing the function's
purpose, the meaning of any input variables, and the significance of any return value(s).
There is no need to include the function name since it immediately follows the
comment.
Example 10. Commenting functions and function groups
^L