Comment Comments are for future maintainers (Score 3, Interesting) 660
I feel that comments can be broken into four types:
- Boiler plate front matter. These are the comments that are required by the coding standards of the shop. Usually contains copyright notices, author's name, list of changes, etc.
- Specification and reference comments. A list of the external references, such as the formal specification for the code, a bibliography for the algorithms used, etc.
- Block comments. These should describe the intent of a larger block of code. The reader should be able to take all the block comments from a program and have a good understanding what the entire program does. Block comments should describe the what and why. Block comments should also describe any gotchas, or special conditions that the maintainer needs to be aware of.
- Line comments. Should describe the purpose of a small number of statements. Line comments should not merely echo the action of the code itself, but describe what is happening and how the particular action relates to the rest of the program.
i += 4;
i += 4;