On Code Commenting And Technical Debt
Out Of Date Warning
Languages change. Perspectives are different. Ideas move on. This article was published on April 29, 2009 which is more than two years ago. It may be out of date. You should verify that technical information in this article is still current before relying upon it for your own purposes.
If you’ve been in development for any length of time, you’ve probably come across a project or a company that doesn’t take the time to incorporate comments into its code. The argument is often made that “our code is self-documenting” and that commenting is just a waste of time, especially if you write clear, clean code. But I disagree.
Some people take a different view of commenting than others. Most recently, Eli White wrote an article called “Commenting on Commenting” in which he argued for commenting virtually every single line of code. He talked about working for a company where they stripped the code out and turned the comments into line-by-line documentation. But commenting to me is important for a different reason:
Failure to comment is simply the accrual of technical debt.
Technical debt is the cost of fixing things that you didn’t fix at a particular point because it would have been too costly. This cost can be in time or money, but represents additional effort that must be made. How does this apply to commenting?
Assume it takes one additional hour per file to write clear, complete comments. To save that hour now, you do not comment your code (before or after you write it), delivering the product faster. However, the next developer to come along and work on that code is going to have to learn about it. Assuming that it would take them an hour to learn about it with comments, and four hours to learn about it without comments, the two hours you saved by not commenting (the hour to comment, and the hour to read them) has cost you four hours of a developer relearning your code, for a total cost of 2 extra hours.
This clearly isn’t worth it.
Undoubtedly somewhere out there someone is going to say something like “wait a minute, Brandon! What if it takes less time?” If it actually takes less time, fine. You got lucky. Think back on your prior experiences, though. The cleanest code you’ve ever seen written by somebody else – how long did it take you to learn? The problem comes not because we write bad code or are sloppy in our design. It comes because we’re human beings and we have to understand the logic before we can modify it. It’s the same reason a doctor who specializes in the heart must understand the other body systems before he can do surgery – even if he never treats any other organs, he must understand how they work together. In the same way, a programmer must understand the logic behind code before they can modify it, and failure to adequately justify your architecture incurs a cost.
This myth of self-documenting code needs to be squashed once and for all. Commenting is important, and unless your code does nothing other than display “Hello World!” it’s going to need some explanation.
Marco Tabini, a man I deeply respect, posted a rebuttal to my argument here. I recommend you read it, as he made some really great points.
Write better object
oriented PHP today.
A brand new book on object oriented PHP that will leave you an object oriented master.Learn more about the book »