3.1 Comment blocks vs scattered comments
Describe a group of logic at the beginning of the file (in the header) or at the top of a block or group of blocks. Avoid scattering the comment for a related logic. Typically the reader would like to go through the comment and then understand the code itself. Scattered comment can make this exercise more tedious.
Example:
//File:
//purpose:
//Project:
//Author:
3.2 Meaningful comments
Do not include what is obvious in the code in your comments. The comment should typically cover what is not expressed through the code itself.
Example:
History of a particular implementation, why a particular signal is used, any
algorithm being implemented etc.
3.3 Single line comments
Use single line comments where ever possible. i.e. Use comments starting with ’//’ rather than ’/* .. */’ style. This makes it easy to cut-paste or move around the code and comments. It is also easy to follow the indentation with single line comments which makes the code more readable.
No comments:
Post a Comment