I ran across a rather cryptic piece of code today but luckily it was commented:
// This cause me 2+ days of debugging work
Seriously though, this is less than useless – it is counterproductive. The comment does nothing but state an irrelevant fact that has nothing to do with the code. Instead, a useful line or two explaining what the code did and, more importantly, why it did it, would save me the same two days of debugging work that are likely to follow.
If you write a comment anywhere, anytime make sure that it:
1. Is relevant
2. Explains WHY
3. Possibly explains what is happening – this won’t be needed in most cases if the WHY is explained well enough
