I’v been reading this great book “Clean Code: A Handbook of Agile Software Craftsmanship” By Robert C. Martin. This book is going to be another classic like the “Code Complete” or “Refactoring“. Anyway, I liked and agreed so much with the author about what he wrote about comments that I couldn’t resist sharing a few lines from the book —-

“The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration.
So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code. Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your ability of expression.”

When we learned programming in our college, we were told by our teachers that you should always write comment! Even when we joined job, our experienced seniors also told us to write comments! It took me a long time to realize that comments should only be used to document some domain knowledge, writing api/library documentation, not to describe code. If you use comments too frequently in every piece of code you write, you should read all three books I mentioned earlier.

Your code should speak for itself. Period.