Comments are for why, not what

I suspect too many dev teams have gone a bit too far the mantra of code should be self documenting. When interviewing developers, this is something I often pick up as a negative signal, is poor commenting style.

So this is just a reminder, that the code tells you what and how, and should be as clearly written as possible for other developers to follow using just the code. But this mantra doesn't mean there should be no comments... comments are still important to indicate to the reader why a piece of code exists.

If a piece of code exists to implement a customer requirement, link to that requirement, external source of information, or simply explain the problem being solved. Otherwise, those who come after you, including yourself, will be doomed to repeat a bug, lose a requirement, or be stuck when changing code later.

See Code Tells You How, Comments Tell You Why - Coding Horror for a better explanation.