C/C++ Programming Style Guidelines
For straight C code, use
/* ...
*/
style comments. For C++ code, use
// ...
style comments. Adhering to these conventions, you can quickly estimate the number
of lines of comments in your code with the following commands:
%
grep "^[ \t]*\* "
%
grep "^[ \t]*\/\/"
Too few or too many comments is an indicator of code that is likely to be difficult to
maintain.
Avoid the use of end-line comments except for variable declarations and for marking
#if/#endif
statements. Make comments be the only thing on a line. For longer
comments describing more complex logic, use a block style to offset them from the
code better. Use block-style comments to describe functions. Use bold comments to
delimit major sections of your code file. Preface all bold comments and block
comments that introduce functions with a form-feed character so that they appear at the
start of the printed page. The following example shows the various comment types in
the C style.
Example 9. C comment types
^L
/*
* ************************************************
* Bold comment.
* ************************************************
*/
/*
* Block comment.
*/
/* Short (single-line) comment. */
