In Defense Of Commenting

« WordPress Caching Slides – Wordcamp Mid-Atlantic

My article from last week, “On Code Commenting and Technical Debt” raised a lot of response throughout the community. I think that discussion is great, and I’m all for a debate that enhances the community. But I feel as though my argument has been taken a bit out of context.

To that end, here are five things that I believe commenting is and five things that commenting is not.

5 Things Commenting IS NOT:

Commenting is not an excuse for bad code. Bad code is bad code, whether you comment it or not. If you’re going to write bade code, please stop and instead learn how to write good code. Good comments won’t make bad code any better. So commenting is not a crutch for bad code.
Commenting doesn’t eliminate refactoring. A lot of the argument seemed to focus on refactoring code. Refactoring is good. Commenting is certainly not an excuse to abandon refactoring, assuming that someone who comes along next can just read the comments and understand. Comments cannot be used to try and remove the need for legitimate refactoring.
Commenting is not for explaining every little thing about your code. Commenting is not for explaining what an if-else statement does. It’s for explaining WHY you have an if-else statement there. Good code should be commented only to explain the reasons behind something, not how something works. Programmers are logical, and they can figure it out.
Commenting is not for justifying poor decisions. Bad code is second only to bad decisions. Architect your application well, rather than writing comments explaining why you didn’t.
Commenting is not for documentation. This might get me into a bit of trouble, but listen closely: despite the fact that great applications exist (like phpDocumentor) commenting is not the same thing as documenting. Documenting involves discussing the signature, the return value, and the purpose. Commenting is leaving little notes about what you’re doing and why.

5 Things Commenting IS:

Commenting is for leaving yourself notes. I often leave myself a note in the code. A to-do. A warning. A “hey this is not right but you didn’t have time to fix it this time around.” These are important. Code is always a work in progress, even if it’s production code (that’s why there’s versions of something – you’re going to eventually make it better).
Commenting is for reminding yourself of decisions. If you’ve spent any time in programming you’ve come back to some code you wrote and gone “why did I do that?” Then you spend an hour trying to refactor it only to discover that it was right the first time, because you spent the same hour doing this a week ago. Why? Because there might be only one logical way to do something. Save yourself the time and write a reminder.
Commenting is for cluing others to the decisions you made. If you’ve ever been asked to implement a relatively simple feature in a fairly complicated and complete application that you’ve never worked with before, you know the struggle it is to not introduce a bug. Comments can clue you in to why a developer made a particular decision (“a dependency over in X function needs this”) and avoid new bugs (or rewriting good code because you think it’s bad!).
Commenting is for highlighting your weaknesses for future correcton. Lots of times you may not have a great solution but you implement something that’s going to need fixing later. Rather than leaving no comments and having the next developer think you’re stupid, you can give them an idea that you know it’s not the best answer. You also can immediately highlight weak spots that you identified when you wrote it the first time.
Commenting is for passing messages between the generations. Keith Casey reminded us in the last conversation that anywhere from 50% to 90% of the software lifecycle is maintaining that code once you’ve written it, and most of the time you’re not going to be the one to maintain it. Comments allow you to pass notes between your generation and the future. If you’re maintaining a software package, or developing a new version, you can leave comments to warn about some ridiculously odd backwards compatibility hack you wrote. You can use comments to alert them to a function that supports a legacy operation. You can leave comments to tell the future programmers important things about your code.

Not doing these things is the accrual of technical debt in the way I described it last week. Because not commenting for these reasons makes your code harder to understand and your application more difficult to maintain, incurring an “interest payment” in order to gain understanding.

Commenting should be used with care. Commenting is not a crutch, and it’s not a fix for bad programming. But when used effectively, it can and does provide a powerful way to communicate ideas, without bloating your code, as some have suggested. And though each programmer’s style might be different, and each shop might hold a different set of rules, the one theme that should ring true is that commenting should be used for helping programmers. That’s what it’s there for.

Acknowledgments for this blog entry really belong to the whole community. Your comments, suggestions, criticisms, and ideas formed the five points for each, and though I’m the one who assembled them in one place, it was truly a community effort.

Brandon Savage is the author of Mastering Object Oriented PHP and Practical Design Patterns in PHP

Posted on 5/4/2009 at 12:30 pm
Categories: Best Practices
Tags: PHP, design, refactoring, comment, code comment, commenting, Community

Daan Broekhof wrote at 5/5/2009 4:17 am:
You should add a
// Todo: Add 5th to things commenting is
there ;)

Cormac wrote at 5/5/2009 5:23 am:
One of the most rational posts so far in this daft commenting debate. It’s very easy to say “your code should be self-commenting” in the abstract, but what’s ACTUALLY important is whether other programmers (including yourself) can properly understand what’s what in a year’s time.