Not all too long ago, while investigating some open source code, I ran across a rather cryptic piece of code. Luckily it was commented:
// This caused me 2+ days of debugging work…
Not only was this not helpful, it was 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 other engineers 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 you are doing a particular action
3. Possibly explains what is happening – this won’t be needed in most cases if the WHY is explained well enough