D.2. General Comments

Comments can make a program much easier to understand, but used heavily or poorly placed they can render good code unreadable. Use them conservatively. Good places to put comments include:

Properties of code should only be commented if they are not obvious. By contrast, even seemingly obvious global properties and invariants may need to be made explicit. However, this doesn't have to be through comments. The assert() macro is an excellent executable comment. There are a few guidelines when writing comments: