Don't Comment Arguments: (write self-documenting code)

• Poorly written or incorrect comments are worse than no comments at all.
• Clearly written, well structured, readable code is much more valuable than comments.
• Comments degrade over time, the code gets maintained but the associated comments don't.
• Good refactoring practices should eliminate comments by replacing comments by well-named single task routines which are self-explainatory.
• Comments doubles the amount of code that programmers have to read to achieve understanding

Do Comment Arguments: (write good useful comments)

• Good comments don't repeat the code or explain it, they clarify it's intent, Comments should explain, at a higher level of abstraction than the code, what you are trying to accomplish.
• Comments act like a table of contents or chapter headings in a book and allow you to quickly zero in on the code you are interested in
• People who don't write comments haven't had the experience of trying to decipher and understand their own code 6 months later...

Actual Solution: Both approaches should be used, write good self-documenting code and at the same time write good useful comments to summarize code, clarify intent, and provide a higher level of abstraction.

-- ShawnDB - 16 Jun 2008
to top