Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Redundancy
Comments are almost always redundant, which means that they're just a repetition of something you've already said in the code. In general programming practice, redundancy is bad, because it means that mistakes are duplicated and changes need to be made multiple times. A good general rule of maintenance: Reduce redundancy.
But in the case of comments, redundancy is the entire point; in fact, the more accurately (and concisely) the comment reflects what's actually in the code, the better. If an algorithm takes a thousand lines of code, a short paragraph explaining its purpose will make life easier on the maintenance programmer, rather than forcing him or her to grapple with the entire mess.
NOTE
If the code and the comment say different things, one or the other must be wrong (or maybe both). Often, it's the comment that's wrong, so the maintenance programmer shouldn't automatically "fix" the code to match the comment.
Redundant comments are often necessary when two pieces of code are physically separated (such as in different places in a file, different files, or even in different languages). Here's an example from a piece of my own code:
/** Issues the request and waits for a response. The caller must ** synch on the socket before calling this. When this is done, ** it must notifyAll on the socket. **/
The word must is a good keyword to look for in a comment. It emphasizes a part of the contract between the caller and the callee that for some reason can't be specified as part of the method signature.