>>The problem as I see is that too many unmeaningful comments actually hurts the readability of the code.
>
>Another critical use for comments that **explain**... it is likely that the explanation is correct, giving you a chance to find the coding error if it is not working as expected.
>
>I agree that over-commenting is a waste of time.
I've had a few good guidelines from Rox, while I worked with her:
- Don't tell me what you're doing here, I can read the code
- Tell me why are you doing it, if you think the code is not obvious
- And specially do tell me when you're doing something out of the regular, so that nobody tries to fix it later, thinking you didn't see the better way to do it. If you had good reasons not to do it this way but that way, write them.
Another fine thing I picked form Steven Black was to bracket nasty workarounds like this:
** KLUDGE ALERT doing xxx because yyy hits the nnn bug in {product/module name here}
{actual code}
** KLUDGE ALERT END