Comments are most likely the spawn of Satan and code monkeys because looking at it like this it’s not so surprising that they are almost always distracting or stating the obvious. A few years ago, at school, my teachers used to tell me: “Use comments in abundance” and alas, how blissfully ignorant I heeded their words at that time.
During actual practice however I quickly found comments a royal pain in the arse – I much more preferred to write readable code. Instead of putting in comments to explain crappy code why don’t spend time refactoring? In a post about the new XML comments for VB.Net in VS2005 Jeff Atwood mentions four essential commenting rules he believes in:
- The value of a comment is directly proportional to the distance between the comment and the code. Good comments stay as close as possible to the code they’re referencing. As distance increases, the odds of developers making an edit without seeing the comment that goes with the code increases. The comment becomes misleading, out of date, or worse, incorrect. Distant comments are unreliable at best.
- Comments with complex formatting cannot be trusted. Complex formatting is a pain to edit and a disincentive to maintenance. If it is difficult to edit a comment, it’s very likely a developer has avoided or postponed synchronizing his work with the comments. I view complex comments with extreme skepticism.
- Don’t include redundant information in the comments. Why have a Revision History section– isn’t that what we use source control for? Besides the fact that this is totally redundant, the odds of a developer remembering, after every single edit, to update that comment section at the top of the procedure are.. very low.
- The best kind of comments are the ones you don’t need. The only “comments” guaranteed to be accurate 100% of the time– and even that is debatable– is the body of the code itself. Endeavor to write self-documenting code whenever possible. An occasional comment to illuminate or clarify is fine, but if you frequently write code full of “tricky parts” and reams of comments, maybe it’s time to refactor.
I totally agree with all of them but the last one is a pet peeve of mine because I strongly believe in self documenting code. That’s also the main reason why I don’t see much value in “paper documentation” like (UML) diagrams or lengthy implementation descriptions. Of course some of these tools are sometimes invaluable during development but their value as documentation is void. The same thing holds true for everything but the code itself.