Friday, January 9, 2009

Comments

A programmer may decide to create only comments on lines of their own68.
You might include some evident information in every C source file:
• a short description of functionality
• a revision date (maybe generated by version control)
• an author
• maybe a copyright
• maybe the revision history (unless maybe managed by version control)
Don't comment the obvious.
Don't use comments as substitutes for speaking identifier names.
Comments can have the semantics of a tool directive (e.g. /*LINTED*/, /*ARGSUSED*/, /*NOTREACHED*/ or /*EMPTY*/ for Lint). They might or might not be used.

Block comments
As blocks represent a functional entity, they are candidates for comments. As constructs that span multiple lines, they should preferably be commented on comment-only lines.
You may consider to put an empty line between blocks to make them a bit more readable. You may generally consider consequent spacing.
In the C language (unlike the C++ language69), a block has two parts: a variable definition part and a code part. These two parts should be separated by a blank line to make them more readable.
I would not recommend to comment the closing brace of a block. A suited editor typically lets the user jump to the corresponding opening brace. The same applies for #endif.

0 Comments: