Code Comments: The Lowest Form of Communication
Recently I’ve been working with lots and lots of legacy code written by lots and lots of people who have been separated by lots and lots of distance between them. As a side effect, a lot of the code has comments that either explain what is going on, rationale behind doing it, and sometimes even a comment providing an excuse or justification and suggesting a way it should be done. It had reminded me of a time on a previous team when we had a new guy with years of experience of solo coding and almost everytime he worked on something he put big huge comments all over the place along the lines of :
/* Here we are using string literals but we should really be using object references */
Which faithfully stayed there for months until someone came across it, yanked it out, and asked him to next time please discuss with us or just do it… we are sitting next to each other after all!
For some reason comments like these drive me nuts! Granted, I don’t think anyone should have any comments in their code at all and should either have code that is self descriptive or explain how the code works via working examples provided in either TestCases or Specs, but comments that make excuses or justify bad practices (or even whine about existing bad code) in my view represent two very large important problems.
For starters, there’s a glaring lack of communication going on, and a comment that proposes a design change or suggestion would be best delivered in the faces of one’s teammates instead of seen silently as a comment when they happen sync that project in to work on a feature a week or month from now. It either represents a weakness to speak frankly with people or a desire to change but a fear of not being able to “make the case”. Either way, one a scale of 1 to 100 in terms of effectiveness and richness of the communication channel, it’s -500.
The second problem it represents, and this is a big one, is the inability to accept responsibility. I’m often reminded of the stages on the way to achieving responsibility in the Responsibility Process that Christopher Avery often advocates, which at the bottom you find Denial, Lay Blame, and Justify. Often when someone leaves comments bitching about the way the code is or what should be done to improve it, they’re really just Laying Blame and Justifying their actions rather than taking action to change the way things are or try to influence those things that they cannot change directly.
Often times, if I see the chance to improve the design of some code that is in my power to change, and my current work I am working on is in the general area, I try to make it happen as much as possible rather than tell myself stories about the way it could be via code comments and pray one day someone sees the comments and implements my suggestions. If I see a chance to improve the design of code that is not in my direct power to change, I try to talk with those who can make it happen… I put a story in our backlog either to remove technical debt or clean up the mess (which I think is a great use of slack). I discuss with the team possible solutions, come up with a plan. I try to take responsibility and make it happen.
Of course, the lowest common denominator is commenting code that is freshly written. Although I can definitely see the forces behind littering legacy code with comments, commenting freshly baked code is definitely a weakness of the highest order… it’s saying that one is going to write lousy code even though their own conscience is telling them otherwise and asserting itself by adding comments to the code they just wrote. When one finds themselves doing this, they should delete the comments and the lousy code and do it right. If they need to explain why something that might not make sense was done, perhaps writing a test case illustrating that weird scenario that requires that tricky code is in order.
Granted, I used to make these mistakes. A long long time ago in an office far away (or as far as you might think Quincy,IL is from St.Louis, MO) I used to write paragraph length comments as well as comments about code I wanted to just get out the door now and clean up later. Boy, did I learn my lesson. Nine times out of ten when I left comments like the ones I’ve been describing in my code and planned to implement them in the future, those fixes fell to the floor and never happened as I had more work coming in the door. If you ask my now, I’d say those bad designs aren’t just composed of the code, but the idiotic comments I left in there as well.
But I’m ranting at this point, but I just really have to drive to the point that in person, face-to-face communication is 500% more effective than a code comment. Code comments as a form of communication is like muttering to yourself something you want to say to someone across the room… how the heck are they going to hear you!? More importantly, how the heck are you going to achieve the changes you want to make happen!? Take responsibility and just do it! 
But to lighten the mood up a bit, you can always look at this thread of awful code comments on stackoverflow. 
If you're new here, you may want to subscribe to my RSS feed. Thanks for visiting!
October 15th, 2009 at 12:22 pm
[...] Carr has written a well argumented post about comments. To sum it up shortly, he says comments are the lowest form of communication, and that commenting [...]
October 19th, 2009 at 1:11 pm
‘No comments’ only works if the code you wrote won’t outlive your memory and your stint with the employer you wrote the code for.
Forgetting that not all development is agile and that many teams are geographically distributed, you need to understand that you and your co-workers won’t be the eventual caretakers of the code.
Whoever takes over control of your code needs to be able to understand it and to understand the low-level decisions that were made in the code. ‘Why does the code always call the service twice in a row?’ ‘Why did you use an array when a hash would seem to fit better?’
You seem to be primarily concerned with ad-hoc coding decisions being made by a single developer who passive-agressively notifies the rest of the team through comments. That’s a management problem, not a reason to ban comments. And it’s the least important problem. Your comments shouldn’t be a communication medium to the developer in the next cube, they should be communications to the maintenance developer two years down the road.
October 20th, 2009 at 9:08 am
Hi Ted,
Thanks for the comments! Amusingly, my biggest pet peeve right now has to do with comments that are in legacy code that I have been tasked with cleaning up and adding new features too.
I’d prefer clear, working unit tests over code comments any day when maintaining code, and I am sure others would too. Which would you prefer? A bunch of outdated code comments that don’t help much or a suite of unit tests/specs that fail if you do something in the code that breaks things? I surely know I would prefer the latter.