To Comment or Not to Comment:
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