On stackoverflow there is a very interesting thread on controversial opinions on programming. From the that thread codes the following quote.
"Most comments in code are in fact a pernicious form of code duplication. We spend most of our time maintaining code written by others (or ourselves) and poor, incorrect, outdated, misleading comments must be near the top of the list of most annoying artifacts in code."
I wholeheartedly agree with the above. It might be tempting to think that adding comments only improves your code. However, that is not the case. I think it is clear that bad comments are worse than no comments. Recently I saw the following in an iterative improvement algorithm:
size_t const iterations = 10000; // just use 5 for now
The comment raises more questions than it answers. Is the code wrong? Is the comment wrong? What does "for now" mean? How the does value change once "for now" is in the past? A better comment would explain how to choose an appropriate value for iterations either based on solution quality or runtime performance.
Further, it can be tempting to add comments to explain bad code rather than write better code. For example, it is easy to write something like the following:
// caller must delete return value some_type_t* some_function();
Eventually someone will forget to delete the return value. Instead of a comment
this policy can be enforced by code. So the above could easily be changed to:
std::auto_ptr means that the return value will be deleted unless the caller goes out of the way to avoid deleting it. So it is no longer necessary to document the policy in comments because it is documented in the code.
In many cases it is possible to reduce the need for comments by improving the structure of the code. This lets the compiler check for inconsistencies and problems which it can never do with comments.