The One True Way syndrome exemplified: the overstated case against code comments

I write frequently, and not without some exasperation, about the perennial search for the “silver bullet” in IT: the holy grail, the end-all, be-all solution to preventing IT failure.

The silver bullet has a very close and similarly pernicious internal twin cousin: the One True Way. That’s a technique or practice that is (usually) adopted by its IT aficionados as the key to overall success, with the important insistence that it will work as long as you follow it to the letter, in all cases, no matter what.

So this post will seemingly be about a specific (and low-level) development issue, but it’s only to serve as an example to illustrate this One True Way syndrome that is so prevalent in IT. At core, my takeaway boils down to the same old message I usually have when it comes to IT matters: be wary of something promising to fix all your problems. Be wary of absolutes. And be especially wary of the combination.

So, let me describe a notable example I ran across recently. Not for the first time, I got into an interesting argument on Twitter. (I’m reminded here, however, of the quaintly delicious observation that “Having a debate on Twitter is like staging a boxing match in a phone booth.”). I’d tweeted a link to an interesting post by Prof. Eugene Wallingford that got me thinking about why developers often have trouble explaining their work, be that in documentation, comments, even design drawings. Wallingford writes,

I’ve been struck by how often [beginning programmers] cannot talk about their code.
When I ask “What is this statement doing?” or “Why are you [x]?”, many struggle. They want to answer in terms of the code they have written, either reading it back to me in English or telling me the code that surrounds it. This is true for almost any value of [x].

Wallingford was writing about beginning programming students, but his words resonated with me, in that in my experience they often (surprisingly) pertain to professional developers as well. So I tweeted that observation, noting that the post gave me some particular insights as to why developers have trouble commenting their code.

To my surprise, my tweet of Wallingford’s article spurred a long dialog with several individuals, two of whom stated adamantly and repeatedly that comments were to be avoided almost altogether in favor of “clean code” that is self-explanatory. (Ironically, this precisely echoes Wallingford’s observation that “They want to answer in terms of the code they have written”). In these people’s eyes, any remaining comments represent a failure (words like “cruft” and “harmful” were used), and are to be employed (they allowed grudgingly) only in “extreme cases” or as a “last resort.” “Every comment is a failure to write code that explains itself,” they said. Even explaining the “whys” of the code in comments shouldn’t be necessary, in their view; the code itself should do that.

This wasn’t the first time I’d encountered programmers opposed to commenting altogether. A developer once told me the story of his hiring interview a year before at a firm where I had just come in as CTO. The shop had gone “all in” on adopting Extreme Programming as a development methodology: mandatory pair programming, intentional spurning of upfront design documents, no bug tracking except via index cards, etc. The interviewee was asked to pair with a senior employee; fine. They worked together on coding a collection class; dandy. The first thing the interviewee did at one point was to dutifully type out a brief javadoc comment explaining what his method expected in terms of arguments, what it was designed to return, etc. Standard stuff. The senior developer complimented him on his due diligence and discipline, then told him that he was now going to erase that javadoc. “But, but, but… WHY?” sputtered the interviewee. The answer: “Because comments just get obsolete. We don’t use them.”

This extreme anti-comment stance is, to me, so contrary to common sense, and to my own experience as a developer and maintainer of code, that I have to step back to ponder its root cause.

The Fallacy of the Highly Skilled

Most notably, I’ve observed throughout my career that highly skilled people often gravitate to using and recommending approaches and methodology that might indeed work really well, as long as everyone else were as highly skilled as they are.

It’s a form of passionate idealism, combined with optimism, coupled with blinders, and mixed in with a tendency to lump contrary opinions into positions they don’t actually hold.

Let’s state what should be fairly obvious: no one likes or can possibly defend useless, rookie-level comments like this:

i++; // bump the counter variable

In fact, it’s easy and even entertaining to come up with bad examples: comments that simply repeat the code, contradict the code, or are self-indulgent or inappropriate. As one veteran developer told me, “Developers are told they have to write comments, so they write comments that at best harmlessly restate what the code already says.” But the “One True Way” school that opposes comments overemphasizes these examples and thus tends to overstate the case against comments in general.

Needless to say, it’s a terrific idea to work towards great design and “clean code”. No one opposes that, and in fact I believe that every programmer should be constantly honing his or her craft to produce simpler, clearer, more maintainable code. Yet, practical concerns do exist that both force compromises and support the need for comments:

  • the team is disparate in its abilities, experience, and even motivation;
  • the people who will ultimately be maintaining the code may be (considerably) less skilled than the person writing it;
  • what’s crystal clear and “obvious” to one person, especially a highly skilled person, may be much less obvious to others. (Consider, for example, the archetypal (even if famously non-canonical) such statement, “Elementary, my dear Watson.” To Holmes, things couldn’t be more clear and obvious; yet, poor Dr. Watson needs constant explanation.)
  • the code in question is due on Friday; (yes, I know this notion (understandably) makes software engineering craftsmen uncomfortable: yet, it’s folly to ignore the reality that deadlines exist).

My Own Descent Into One-True-Way-ism

Here’s a personal illustrative example from a slightly different domain: I don’t use spell checkers, basically ever. I find them annoying and much too prone to alerting on “false positives.” Instead, I proofread my material carefully and find the errors. That happens to be a particular (albeit admittedly societally useless) strong skill of mine, honed through years of activity in both software development (where typos count) and journalism. And, I’ve noted that people who rely on spell checkers often miss really obvious, painful errors: their two busy too sea um. Or they do things such as correct “alot” (by which they mean “a lot”) to “allot”, just because the hapless spell checker suggested it as the fix.

Given that errors can be missed or even created by relying on a spell checker, and my lack of need for a spell checker myself, should I now recommend that people “do the hard work” and learn to do as I do: proofread their text carefully on their own? Of course not. That would be very idealistic of me, but it would also be quite misguided. Most people out there aren’t as dogged or adept at proofreading as I happen to be, so using a spell checker actually does help them catch a lot of mistakes that would otherwise go unnoticed. Some errors don’t get caught that way, perhaps, but on balance, the result in most cases is better. To eliminate the use of spell checkers altogether, simply because they can be misused or imperfect, would be throwing the baby out with the bathwater, based on a very faulty assumption that everyone “should” be able to catch their own typos the way I happen to be able to.

Comments and “clean code”: not an either/or

But back to comments: I’ve been programming now for longer than I like to admit: decades. Since I don’t code every day anymore, I’m particularly motivated to use many “clean code” precepts, as a self-defense mechanism: revisiting my own code even a few short months after I’ve worked on it can be a nightmare if the code itself is not as as clear and maintainable (and yes, self-explanatory) as possible. And for the very same reason, I comment my code, even if it feels a little redundant at the time. Whenever I’ve had to maintain code, whether by me or someone else, I remember how profoundly grateful I’ve been when the code has also contained “bread crumbs” (in the form of appropriate, useful comments) that let me easily revisit why particular choices were made or which explain the deeper context of the immediate chunk. “Clean code” and useful commenting really doesn’t have to be an either/or, and it makes no sense to insist that it is.

Moreover, what is often missed in this debate is acknowledgment of the kind of “chilling effect” that influential books and blog posts and tweets create when they so categorically state that “comments are harmful.” In particular, the less experienced, less idealistic developers will take away the work-easing aspect of that (i.e., don’t bother to spend time commenting), without necessarily absorbing and implementing the true precepts of clean code as a prerequisite. In truth, not everyone will be as committed to clean code as the clean code proponents imagine, for a number of the practical reasons I’ve cited above. When you rely on having made code “self-explanatory” and you shun comments altogether because of that assumption, you miss the obvious and common situation: one person’s “self-explanatory” code may look, to a future maintainer, more like a big ball of mud than the author can possibly imagine when he himself is knee-deep into creating it. There’s nothing wrong with judicious and targeted comments that provide the beneficial sort of bread crumbs that help out later maintainers.

So here’s the thing: for solid and laudable reasons, software craftsmen start out warning folks to be cautious and targeted about when they use comments, but they then take that stance to extremes, embracing an impractical, blindered, fringe view that pigeonholes all comments as signs of failure. At its most extreme, part of that stance even seems to turn into accusing the other side of not having a true zeal for excellence or being too willing to make compromises on quality.

A balanced view should prevail

It’s much more sensible to take a balanced view, as does Steve McConnell in his book, Code Complete, noting that “done poorly, commenting is a waste of time and sometimes harmful. Done well, commenting is worthwhile.” That’s quite different from pronouncing all comments to be failures, as did my Twitter conversationalists, and as does Robert C. Martin in his otherwise excellent and useful book, Clean Code, in which he writes: “Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them”.

Again, then, I return to the practical side of things, and strongly counsel against advice, even from consummate craftsmen, that smacks of an absolutist, One True Way approach and which contradicts common sense. Claims like “our approach will solve all your IT failure problems”, and the claim that “all comments are failures; avoid using them” are cut from the same cloth. Don’t buy it.



  1. Peter, in my IT tenure I have definitely run across the exact arguments you’ve outlined. As the conversation around how to/not to comment and/or document code progresses, it seems to move from discussing pragmatic need to almost religious/political ideological debating.

    Another element that I believe factors into the discussion of code documentation is that of the coder’s desire to be the “IT hero”. In my long list of topics I have writen about on my blog, the “IT hero” is one I don’t know why I haven’t already covered given it creeps into a number of these “why IT people do what they do” contexts. IT heroism enters the code comment/documentation conversation, in my opinion, when the ego of the coder and the need to be “the only one who can come in and save the day” when a tough problem is discovered. If the coder thoroughly comments or documents the code such that others can more easily understand it, and, heaven forbid in the IT hero’s mind, make autonomous changes to fix the problem without the IT hero’s involvement, good commenting, mi-optically, devalues the IT hero in his/her own mind.

    Thus, the IT hero coder shies from commenting/document entirely, or only enough to remind themselves of why they constructed a particular object a certain way or slaps in enough verbiage to pass a QA check-box test of “is the code commented, yes, so ‘check’, moving on …”. This, in my opinion, results in the IT hero being highly unpromote-able, not a team player and even untrusted by senior management as he/she becomes more of a threat than a valuable asset in extreme cases.

    My experience is predominately in large corporate IT shops where IT isn’t the company’s main stay. Thus, not sure how much of this heroism example manifests itself in startup/SMB/IT centric shops.

    Anything in my comment resonate with you?

  2. Yes, I’ve been there, seen that, even DONE that very early in my own career as a developer. Some people never progress beyond that attitude, sad to say. And it takes a particular breed of manager/exec to stop honoring and rewarding the “heroes/gurus” approach, because it seems like those people are the ones who can pull things out of the fire when you really need it. But as you say, it becomes more of a threat than a valuable asset. Very astute observation, John. I have a whole post in mind, some day, about the heroes/gurus syndrome that has forever been a part of IT.

    Thanks, as always, for commenting!

  3. Noticed your post from your link to mine. Pretty good writeup I think, the “one true way” as you describe seems to be a big crippling factor with some developers in my experience. They try to think of the “proper” way to do things which they seem to believe is the only good way to do it because they have heard someone write about it on the internet.

    Personally I try to advocate doing the sensible thing, or what seems the correct thing to do right now. Don’t build useless layers or complications (f.ex. design patterns just for the sake of using them), and apply comments if you feel like it will help (but not just because “you have to”).


  1. […] for these novels is that I look for nuanced presentation, not pat answers that amount to a “one true way” advocacy. (In The Phoenix Project, the one true way consists of Three Ways, but I digress). […]

Speak Your Mind


This site uses Akismet to reduce spam. Learn how your comment data is processed.