When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous.
Refactoring: Improving the Design of Existing Code by Martin Fowler, Kent Beck (Contributor), John Brant (Contributor), William Opdyke, don Roberts
ISBN: 0201485672 This book is available from
Good code is its own best documentation. As you're about to add a comment, ask yourself, 'How can I improve the code so that this comment isn't needed?' Improve the code and then document it to make it even clearer.
Commenting your code is like cleaning your bathroom - you never want to do it, but it really does create a more pleasant experience for you and your guests.
Don't comment bad code ‐ rewrite it.
The proper use of comments is to compensate for our failure to express ourself in code.
Code never lies, comments sometimes do.