Anyone who has programmed for any length of time has an opinion about comments in code. They're essential. They're not essential. Commenting is actually worse than not commenting. It runs the gamut. I'm beginning to understand more and more that comments are actually a disctraction to clean, clear, concise code. Especially when writing in Python, it is possible to write code that requires no comments, but is still 100% understandable and discoverable. Sometimes a line or two is required to explain something not clear from context, but it's rare.
After reading a piece by Steven Smith entitled
Comments in Code Indicate Functions Trying To Escape, my lead programmer
Troy Melhase (i.e. my "boss"), who is a strong proponent of clear code/no comments, wrote:
Yes. Instead of writing comments, write code that doesn't need
comments.
Clear, and concise, just like his code. After musing on it a while, his ironic streak kicked in, and he composed the following "epic tome," as he describes it, that so clearly illustrates the many useless blocks of comments I have seen in my time as a programmer. He gave me permission to post it, so here you go! Enjoy.
(BTW, visit Troy's blog. He's written a Java to Python translator, and has a really cool stock-trading and analysis application.)
#
## Summary: Explain why excessive comments suck.
##
##
## Author: Troy Melhase
## Email: troy@gci.net
## Date: 05/01/2008
##
##
## Detail:
##
## Comments like this serve no purpose because you have to read all of the code in this file anyway.
## So here you are, reading useless information that I put here to satisfy a thoughtless policy
## or an academic belief. I could explain what the code does, but it's easier to blat out mindless
## drivel that is easily mistaken for insight or actual work.
##
## Even if I do add useful information to the code below (doubtful), someone will have to edit this
## information as the code changes. That's like writing the code twice, and of course that doubles
## the chances of introducing a bug.
##
## Plus, I've distracted you from your purpose -- reading! Reading code can be difficult without the
## additional burden of constantly shifting gears between executable code and non-executable code (these
## comments).
##
## If you've made it this far without giving up, you should realize that I've still added zero information
## to the subject and wasted your time in the process. The original reply is still better, and you should
## aim to adopt it as professional and personal coding policy.
##
## In case you missed the original reply, and in hopes of finding it here, buried at the bottom of this
## epic tome (aka epic fail): Instead of writing comments, write code that doesn't need comments.
##
##
## Plus: extra file encoding type cruft.
## Plus: extra editor hint cruft.
## Plus: extra version control meta data cruft.
## Plus: version control history that should be left in the version control system.
##
Now, this doesn't preclude
documentation--we use doc strings at the beginning of files, functions, and classes quite heavily--but in-line comments in code are rare.
