Why not to comment code
Posted by Ronnie on August 15th, 2009
Update, Aug 18, 2009: I’m amazed at how much attention this post has received. More than 200 comments on Reddit.
I was just listening to the Why comments are evil episode of Deep Fried Bytes. The views put forward by the guest, Corey Haines, deeply resonate with me because I believe they’re what every developer should strive for. I’m not advocating that code should be entirely free of comments, but that most comments do more harm than good.
Below I’ve listed what I consider the main points of view — or pearls of wisdom — from the episode and included my own commentary.
- It’s important to differentiate between code comments and API documentation. For API documentation, don’t auto-generate. Especially don’t go with tools like GhostDoc. Take the time to document properly. Otherwise, you’re more likely to confuse the developer trying to make sense of your code.
- Stop focusing on having the computer understand you and start focusing on the person that comes after you, e.g., while there’s some overhead to method calls, unless the profiler tells you otherwise, don’t hesitate to break down a method into as many smaller methods as it takes to make it more approachable.
- Every time you’re tempted at writing a comment, take the time to think if you can make the code tell its own story, e.g., instead of some branching condition, extract the condition into a method to emphasize the story of why over how.
- Developers comment to explain a confusing part of their code, rather than take the time to refactor it by extracting a method or naming a variable properly. Inevitably the code gets modified and the comment rots.
- Parts of a method may be complicated so a comment is added. Saying part of a method is complicated is in itself a sign that it’s doing too much.
- The prevailing culture among developers is to focus on what it takes to get code working. It’s a battle of short-term vs. long-term maintainability, and short-term almost always comes out as the winner. Writing code, ask yourself if you’re able to immediately understand the code a month from now.
The opinions put forward in the episode aren’t new. Still, I find them well worth iterating because as developers we tend to not pay enough attention to them.
While refactoring is probably as old as programming, Martin Fowler’s 1999 Refactoring: Improving the Design of Existing Code turned it mainstream. Others have followed it his footsteps advocating for the larger concept of software craftsmanship. Most notably Uncle Bob, who delivered an excellent talk on the subject at Øredev 2008.
On a personal note, I once worked at a consulting company where every new employee was handed three books on the first day of employment. One of these was the Refactoring book. The others were the seminal Design Patterns: Elements of Reusable Object-Oriented Software and Writing Effective Use Cases. I think that reveals something important about that company’s culture. Sadly, most companies aren’t that specific on issues of code quality.
August 16th, 2009 at 8:20 pm
I liked your article, even though many of your points are (hopefully) widely known. It reminded me of the ‘Comments’ section of the CodingStyle doc that Linus Torvalds wrote and is included in the documentation directory of the Linux kernel:
http://www.kernel.org/doc/Documentation/CodingStyle
Commenting, with regards to over-commenting and under-commenting, is a little bit like pulling shots of Espresso. If you run them too short, they taste very acidly and sour, if you run them too long they become an unpleasant bitterness
August 17th, 2009 at 12:19 am
It’s very true that comments shouldn’t be needed to explain what your code is doing.
But that was never the point of comments. Comments are needed to explain *why* your code is doing what it’s doing.
August 17th, 2009 at 3:47 am
A useful quote: “Rules are for fools and the guidance of wise men.” – Sqn Ldr Dale “Spud” Murphy (no, not the mythical Murphy of Murphy’s Law fame).
I’m always wary of black and white statements – You must do this, you should never do that. And so it is with commenting code.
I agree that many (perhaps most?) comments are useless. However, comments are still useful for saying WHY you’re doing something in a particular way. To get around some obscure bug in someone else’s code, or to deal with a particular, not obvious, user case, for example. You can refactor code as much as you want but I don’t think it will explain to a maintenance coder (eg yourself a year down the track) why the code was originally written the way it has.
August 17th, 2009 at 4:01 pm
[...] though I’m a great advocate of commenting code, there are those thank think commenting is not always a good thing. As stated in the linked article, we must differentiate between API documentation and normal, [...]
August 17th, 2009 at 7:08 pm
I always find it difficult to keep the comment in synch with the code. Whenever I need to change the code, the comments are also needs to be updated, thus doubling up my work.
August 18th, 2009 at 4:01 am
The thing is many programmers are not perfect. Though they know what they want the code to do, they don’t always get it right. This leads to bugs. Now to help the next programmer working on this code to find the bugs, of confirm the code is bugfree, it is necessary to also state in human language what the code was supposed to do. So yes, it is necessary to document your code, unless you’re the perfect programmer. I haven’t met one yet.
December 28th, 2009 at 1:29 pm
[...] Why not to comment code [...]