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.
Be the first to get Modern Object-Oriented PHP!
Long to learn how you can develop modern applications using object-oriented PHP? Curious about how to apply all these best practices to your code?
Modern Object-Oriented PHP is a brand-new book focused on teaching you the techniques you need for writing modern, well-designed object-oriented applications!
The book lands in April. Sign up today for a sample chapter plus special launch day discounts!