> I agree that one should make code very readable but comments can be very useful. Just because someone uses the tool incorrectly doesn't make it a useless tool.
Actually, I think the problem is people tend to make comments which attempt to explain the function of the code at more than a high level. This is the mistake.
Your comments should explain the "why" of your code but seldom go into the "what", because the "what" will almost certainly change. And in fact, in many cases the "what" may not be entirely determinable from a single point in time with properly uncoupled code.
You can sit here and say "Oh yeah well its the developer's problem to update the comments don't blame the comments." but the observation that "what" comments get out of date is so universal that we should probably accept it as the norm.
I can't disagree, but I still feel that the comment blames the tool instead of the misuse. If you feel explaining "what" in the comments is bad practice, then it is the fault of the developer that wrote the "what" instead of the commenting.
Based on responses to my comment on this, I'm beginning to wonder if I need to approach explaining my thinking on this in a different way.
> If you feel explaining "what" in the comments is bad practice, then it is the fault of the developer that wrote the "what" instead of the commenting.
Do you think misleading comments should stay in place then? I'm confused why this matters.
I don't see how it could be seen I was saying that. I thought I was clearly saying that misleading comments are the fault of the person who wrote them and not the thought of comments in the first place. The original controversial thought was that comments were too annoying to be useful, my reaction was that was blaming the tool instead of the person misusing the tool.
To answer your question, a misleading comment should of course be removed or changed. Again, I fail to see how I was suggesting otherwise.
Actually, I think the problem is people tend to make comments which attempt to explain the function of the code at more than a high level. This is the mistake.
Your comments should explain the "why" of your code but seldom go into the "what", because the "what" will almost certainly change. And in fact, in many cases the "what" may not be entirely determinable from a single point in time with properly uncoupled code.
You can sit here and say "Oh yeah well its the developer's problem to update the comments don't blame the comments." but the observation that "what" comments get out of date is so universal that we should probably accept it as the norm.