Ben Nadel
On User Experience (UX) Design, JavaScript, ColdFusion, Node.js, Life, and Love.
I am the chief technical officer at InVision App, Inc - a prototyping and collaboration platform for designers, built by designers. I also rock out in JavaScript and ColdFusion 24x7.
Meanwhile on Twitter
Loading latest tweet...
Ben Nadel at BFusion / BFLEX 2009 (Bloomington, Indiana) with: Peter Farrell and Matt Woodward

Not Commenting And The Tipping Point Of Poor Programming

By Ben Nadel on
Tags: ColdFusion, Life

Just this morning, I have read three different blog posts about why people should not be commenting their code (ok, that's not exactly what he was saying, but it is what the blog post title implied). Most of you know that I am strongly against this idea, and as you can see from my public code, I put a large amount of comments in my code. After reading Brian Kotek's "Don't Comment Your Code," I felt I had to weigh in on the subject myself as the devil's advocate.

WARNING: The following is a pure opinion piece, leave now if you are seeking technical information.

I recently finished reading Malcolm Gladwell's, The Tipping Point: How Little Things Can Make A Big Difference, and it really emphasized to me why posts about not commenting your code can be very dangerous. The majority of people are quite easily influenced. Most of the time, we are just subconsciously looking for an "excuse" to do something. To find these excuses, we often times look to icons and thought-leaders for the "go-ahead" to act a certain way. If you don't believe me, all you need to do is hear about Gladwell's example of the suicide rate in Micronesia - After a well known Micronesian "romantic" killed himself, the rate of suicide among teens in Micronesia exploded. And youths who had tried to kill themselves and failed, when asked why they had done it, replied that they had heard about it and wanted to "experiment" with suicide to see what it was like for themselves.

Now, I know what you're thinking - suicide and code commenting are hardly in the same ball park. But, that's exactly my point! If people can be so easily influenced by icons on subjects as extreme as suicide, how much more easily do you think it will be for them to be influenced by something as mundane as the practice of code commenting?

Brian points out that code should be self-documenting - that it should be written in such a way and with such clarity that just looking at it should reveal what it does. While I agree with the fact that code should be written this way, I think that having thought leaders in the ColdFusion world saying that clean code is enough might very well provide the tipping point of poor programming (making the big assumption that poor programming is not already rampant). It's one thing for a person, such as Brian, that writes very high quality code, to keep his comments to a minimum. But what about the majority of people who are not at his level? These are people who are not writing great code to begin with - are they going to view these blog posts as the excuse and justification to stop commenting their code? What happens then? We have an epidemic (as Gladwell would put it) of poorly written and poorly commented code.

Will this happen? I don't know. But, from what Malcolm Gladwell has taught me, little things can make a huge difference; the trends started by few can lead to epidemic behavior of the masses. As such, I think it is important that icons of the ColdFusion world do emphasize commenting as a best practice such that others will see it and follow suit.

I don't mean to single out Brian in any way; he's a great programmer and I hope to one day to have his handle on OOP and application architecture. His was merely the last blog post that I read on the subject. Brian also makes some very good points in his blog post and in the comments to his post. I am merely trying to play devil's advocate to keep things in perspective.



Reader Comments

Thanks for this post, Ben. I had much the same thought. Not that anyone I will target with the next statement will see this comment but "Read the entire article it's not saying don't use comments, it's saying don't use comments to make up for bad coding practices."

Brian's point, I think, was don't write an obfuscated piece of code and try and make it all better with a comment. Rather write that code into it's own function that is named "ConciseDescriptionOfWhatCodeDoes." It's a better practice that pays off other ways. Then save comments for things like "Pulled in Java LDAP class because CFLDAP barfed after 6,000 records."

Or in other words, don't use comments for explaining what you are doing, if you write code clearly enough you don't have to , rather use comments to explain why/how you are doing what you are doing.

Reply to this Comment

When going through school, it was always preached to comment your code. I did for my projects and for my own benefit.

When I started out professionally, my mentors did not comment their code because there wasn't "enough time." I did pick up this bad habit, but have recently corrected myself and began commenting again. I may code something and go back to it later and not know what is going on as my techniques have improved. Maybe I can rewrite it to be more efficient. I realized I'm not the only one who looks at what I do. I may complete a process one way when my colleagues may do it differently. The comments will help them understand what I did. Lastly, when I leave my current position for future opportunities, my replacement may be fresh out of school as I was and have no idea. My comments could serve as stepping stones.

Commenting = good.

Reply to this Comment

Commenting code and writing readable code are one and the same, in my view, just the latter is more concise. If you don't have readable code, comments are needed, but they bring with them a maintenance burden because you're double representing. It's far easier to write your code in a readable way so you're single-representing it.

I'm not just talking about poor code either: some nasty algorithm that can't be implemented efficiently without some crazy code absolutely needs separate documentation. This is about the only place I comment my code.

It's also worth discussing different types of commenting. I've seen a lot of code where every line has a trailing comment over to the right explaining what the line does. Totally useless. Comments should explain at a high level what the code is about to do; if you care about the nitty gritty, just read the code, regardless of how nasty.

However, get too high-level and it's just as bad. I've seen Fusedocs for 1000 line files that are a sentence long. Not only does that provide no real information, because it's so separated from the code, the chances of it getting update (remember, it's a double representation) are about nil, so it's not mostly useless, it's actually harmful because it's probably inaccurate.

So like everything else, there's a sweet spot for comments in code. I think people generally comment too much when they're starting out, because they're bad coders. The "don't comment your code" guideline should be exactly that, a guideline for helping people notice when they're writing code that could be improved to not warrant commenting. I.e. people should use the desire to comment as a warning that their code should be refactored. As people become more proficient, the comment level decreases, as the code improves in quality.

NB: example code and such is orthagonal to "real" code in this sense: example code is design to instruct, so very low-level comments are expected/desired.

NB: code-level documentation and application-level documentation are often mixed (e.g. JavaDocs). The two are distinct, and I (and Brian) am talking only about code-level docs.

Reply to this Comment

Just to cast my vote, I have to agree with Terrence. I (almost) never write comments that explain what I am doing. Instead, (nearly) all of my comments explain why I am doing it in this particular way.

The only exception to this rule is when the why part has led to an implementation that is so very, very strange that the code might not impenetrably indecipherable. Only then do I include what comments -- in which case they are more like wtf comments.

But these instances are extraordinarily few and far between. On the order of less than a half-dozen a year, I'd say.

Reply to this Comment

Ben, I think perhaps the title in Brian's post was the poorly chosen part of it. The actual advice, that comments are indicators that your code is bad, would have been a better title.

Then people could cite it and there could be no confusion about the actual advice contained therein.

I should also say that I think anyone who reads that post and misrepresents it as an excuse to do evil and lazy things is probably going to do evil and lazy things with or without an expert opinion "backing them up."

Reply to this Comment

Barney hits the nail on the head (as usual!) While advising people not to comment their code but instead to just write clear code has a potential negative, the reverse is arguably worse.

Advising people to comment the heck out of their code can not only lead to bad code (sure it's complicated, but this comment explains it!), but creates a duplication of knowledge that now has to be maintained. Any change to the commented code requires updating the comment as well. And if one forgets to do this or is in a hurry, things go downhill rapidly. Because incorrect comments are far worse than no comments at all.

Further, many folks think that just adding a redundant comment to a code block is good commenting. We've all seen --Loop over array-- and --Execute query-- type of comments, which add no additional information at all. Until they decide to step back and examine the actual reason for the comments, as well as considering options for minimizing them by writing/refactoring to clearer code, this will probably continue for as long as programmers write code.

To be sure, knowing "how much commenting is enough" is something that must be learned from experience, through trial and error. Just like most other best-practices. The fact that it takes some effort and thought to internalize these ideas doesn't mean the advise shouldn't be offered. ;-)

Thanks Ben, good thread of ideas bouncing around on this!

Reply to this Comment

Good post. I think Brian has a point as Terrence pointed out. Nonetheless, I think your discussion of tipping points is a good one. I have had more than one person, for instance, tell me that the policy at their office was to put absolutely everything into stored procedures because a boss had read that they gave better performance. Now, nevermind that the dynamic queries they used offset the performance gain (since the execution plans were not cached) or that it didn't make sense to put most of these queries in stored procs. So and so. who was an authority, had said they performed better and that was enough reason to make a senseless policy.

Reply to this Comment

Sami, to be fair, the very first line of the post explains why I chose that title so there's really no way anyone should miss the point of it if they actually read the entry. ;-)

Reply to this Comment

I think these are all valid points. Again, I was really trying to provide a devil's advocate point of view. In practice, I agree with much of what is said here. My initial fear, which I think was triggered by seeing three similar posts in one day about the "negative" aspects of commenting and it made me think of the Tipping Point and I just kind of connected those two dots and wanted to put it down on paper to bring to light something that maybe no one thought of.

I really like Barney's like:

"As people become more proficient, the comment level decreases, as the code improves in quality."

I think this is the best lesson to take away from the conversation.

And, what Sammy said:

I should also say that I think anyone who reads that post and misrepresents it as an excuse to do evil and lazy things is probably going to do evil and lazy things with or without an expert opinion "backing them up."

Very true :)

Reply to this Comment

... and to be as humble as possible, I am definitely guilty of having comments like:

<!--- Query for colleges. --->

I know that doesn't mean anything at all, but even so, sometimes I have a query that joins like 5 or 6 tables, and having that summed up in such a simple comment can clarify the "intent" of the complex query.

But, like what everyone is saying, there is a spectrum of usability. Having a comment like that above a query that simply pulls from a property table would be totally useless.

Reply to this Comment

Oh, I agree Ben, we need Devil's Advocates sometimes to foster discussion (I've been known to do it myself heh). The connection to the tipping point was also very insightful! Overall this idea also reminds me of the "Broken Windows" section in "The Pragmatic Programmer".

Reply to this Comment

@Brian,

I have to say that the "broken window" concept is really the only thing I actually remember from the Pragmatic Programmer :) I don't know if it was the only thing I could connect to a skill level at the time of reading (a few years ago), or what, but something about that concept just connected with me.

When I know I am cutting corners, I try to think about it and the slippery slope that it leads to. That doesn't always stop me from cutting corners, but at least it makes me feel guilty.

Reply to this Comment

Ben,

I read Brian's blog and I think there's a bigger issue than whether to comment or not. That issue is how readable our code is. A comment like "loop over the query" is, as you point out, useless. But simply moving a bit of code to its own function (as Brian shows) doesn't necessarily solve the problem.

When code is trivial, few comments are needed. But when code gets complex (when it's often accompanied by multiple method calls), there needs to be some way of making the overall intent of the coder plain. Code, after all, is read far more times than it's written. And maintaining code -- a risky task in all but the most trivial of cases -- is made foolishly hard by programmers who don't express their intent.

Here's my recommendation: write your comments BEFORE you write your code. Because this is such a crazy idea, let me repeat it: Write your comments BEFORE you write your code. Why? Two reasons: 1: it will force you to think through what you're trying to do before you do it. 2: it will make your intentions clear to those who must maintain your code, even if that person is a future you who no longer remembers exactly what that tricky code is doing.

I like to number and lay out the steps I'll be doing in natural language. The ideal is that, without any code, someone can see what I'm doing. Then any competent coder can implement that code. They might not do it just the way I did, but that's fine. The comments form almost a recipe, if you will.

That issue is, as far as I can see, almost completely ignored by coders. I read a comment about Ray Camden having trouble with jQuery because of its terseness. But making code bigger (and thereby more explicit) misses the point: it's code. It's OK to be small, obtuse, and dense if it needs to be (regular expressions, anyone?). But if the intent is made clear -- and I know no better way than through comments -- the code can be small and we won't need "loop over the query" type comments.

The need for this "literate programming", to borrow the phrase from the great Don Knuth, is enormous. I would recommend this to anyone who aspires to beautiful code.

Reply to this Comment

I totally agree with Hal's recommendation here. I often do this...not all the time, but honestly the write comments first method gets exponentially more helpful the more complex or obtuse the code gets. Obviously this benefits someone who comes back and reads my code but it also serves as placeholders for code/logic before I dive into the details.

Reply to this Comment

Good points as always, Hal. This also seems to dovetail into the idea of "programming by intention" that I try to adhere to. Basically, when writing some complex code, I start by writing out a top-level or "sergeant" method which does nothing but call other methods. These other methods will usually be private (sergeant-private ha ha) and haven't even been written yet.

So the idea is to write out your ideal set of method calls that would do exactly what you want to do, in advance. Something like

public function sendInvoice(invoiceID) {
invoiceData = getInvoiceData(invoiceID);
invoice = renderInvoice(invoiceData);
mailInvoice(invoice);
}

Because I'm doing this in advance, I am free to think up whatever will work best and name them as clearly as I can. I can also concentrate on trying to make each individual method as specific and cohesive as I can. From here I would go on and create the individual private methods that are needed.

I've found this approach to be quite effective. It isn't exactly the same idea that Hal is putting forth about commenting out the steps in a complex task, but it is a similar idea.

Reply to this Comment

@Hal,

I try to do that for more complex pieces of code; otherwise, I find it hard to even start the problem as it will feel to overwhelming without a basic plan of attack.

In conjunction with that, one of the things that I have started to utilize is the TODO comment. I use homesite, but I am modelling this after the TODO functionality built into CFEclipse. Basically, I can search for all the stuff that needs to get done.

If I take that concept and combine it with "Why" style comments, then I find that I can even skip steps that are too complicated or not necessary at the moment and come back to them when other basics are in place.

Reply to this Comment

<!---
author: charlie griefer
date created: 05 june 2008
purpose: to comment on ben's blog

description:
this is where i post a comment to ben's blog stating that i agree with brian... while i would never say "don't use comments", i would simply say "use comments where necessary". to reiterate some of the points already made, i think as we progress as programmers, the frequency with which we need to do that diminishes... but will never completely vanish.
--->

<!--- begin blog comment : this is where the blog comment starts --->
i agree with brian... while i would never say "don't use comments", i would simply say "use comments where necessary". to reiterate some of the points already made, i think as we progress as programmers, the frequency with which we need to do that diminishes... but will never completely vanish.
<!--- end blog comment : this is where i'm done saying what i set out to say --->

<!--- begin smiley to indicate that i may have gone overboard --->
:)
<!--- end smiley to indicate that i may have gone overboard --->

Reply to this Comment

Not commenting? Thank you . . . you just made my work a lot harder. I'm not a mind-reader, and I don't have time to try to figure out what the heck you were doing. As it is, there's not enough documentation. People come and go, but the code remains and it's unfair to the business to be left with code that nobody can make heads or tails out of.

Reply to this Comment

That's the whole point Lola. If you have code that no one can make heads or tails out of without comments, then something is wrong. The code needs refactoring to make it more clear. Well-written code doesn't *need* comments to explain what it is doing because the code is self-documenting and easy to read and follow.

Reply to this Comment

I'm currently in a shop that is new to O-O and CF8 and comments in my code help to:

1. educate team members on the tags/approach/framework that I'm using
2. allow developers unfamiliar with my projects to jump in and make changes while I'm on vacation

So regardless of Mr. Kotek's views my code comments have served my team well & afford me some peace and quiet while I'm kicking back on the beach!

Reply to this Comment

"Or in other words, don't use comments for explaining what you are doing, if you write code clearly enough you don't have to , rather use comments to explain why/how you are doing what you are doing."

Agreed.

In fact, large numbers comments describing what could violate the DRY principle and result in 'left behind' comments that subvert their goal.

Keep the code clear, your target user in that context is other developers (including your future self). Comment when necessary to add clarity or reasoning, but if you comment too frequently, you'll just be repeating yourself as demonstrated above.

Usable code significantly improves maintainability.

Reply to this Comment

@Christopher,

First off, I just want to be clear that Brian is not anti-comments; he's just pro-smart-commenting.

That being said, I know how you feel. I think there are two different types of programming - one that gets the job done effectively and one that teaches other people. I think those two types of programming require different types of commenting.

For example, the code I post on my blog is mean to teach people more about ColdFusion and web development. As such, it has a bit excessive amount of comments to make sure that everyone who reads it knows exactly what is going on. The comments that I put on public code are much larger, longer, and more thorough than the comments I put in my standard code. This is because I don't need to hand-hold anyone in my regular code - it is being read and used by developers.

So, in your case, when you have a team that is new NOT just to an application, but also to a programming methdology, I think it is quite appropriate that a good deal of comment "hand-holding" is done until the entire team gets up to snuff on the new techniques.

Reply to this Comment

Thanks Ben! Yes, it seems that some folks are missing my point, so maybe my attempt at an attention-grabbing blog entry title has backfired if people didn't read it and just saw the title. I absolutely think comments are useful and essential for things like documenation, TODOs, and explaining *why* something is happening. What I am against are redundant comments, or comments that explain *how* something is happening, which unfortunately seems to constitute most of the comments that encounter.

cheers,

Brian

Reply to this Comment

Ben,

I think your A-list comment panel has covered all the bases about commenting. I wanted to add a note about tone.

A famous theologian once said "Mundis Vult Decepi" - the world winks at deception. I think it was Martin Buber. In any case, your comments on "the majority of people being easily influenced" made me think of it. Given the choice between a plausible lie and an uncomfortable truth people tend to gravitate toward the lie.

I wonder however, if by labeling something as "dangerous" rather than just "ill advised" you are not setting yourself for accusations of being paternalistic and pedantic and.... and.... sorry - I can't think of another "p" word. Oh.. I know.. patronizing. As a friend I would caution you. I'm sure that comments or sans comments the IT world will still be standing tomorrow :)

Reply to this Comment

Good post :) In general i dont mind people commenting stuff but what really does my head in is when people comment out huge blocks of code itself. Ie i opened a page the other week that was 600 lines long, but over 300 of them where commented out, i was like £%£$%$%^ and did a bit of screaming:)

Alien Boy

Reply to this Comment

To my mind, the issue isn't "don't write comments to make up for bad code", it's "write good code, write good comments".

Poorly written comments are as bad as poorly written code - sometimes worse, because every comment tends to be read, where code doesn't.

Self-documenting code is a myth, in my opinion.

I comment my code to the audience I expect - as a result I tend to wind up with more comments than is possibly necessary, but given I'll likely forget what I was doing, how and why I was doing it in 3 months time when I'm asked to change something, a comment can do wonders to help me find what I'm after and remind myself what/why/how I did things.

Additionally:
I can read English far more easily than I can read code - so I find I can write useful comments. Perhaps not every coder has this advantage.

Reply to this Comment

@Jono: I guess the main difference then is that I think that self-documenting code is not only very real but is absolutely essential. As I've reiterated a few times now, the issue with using comments to explain what code is doing is the duplication of information that it causes. Every change to the code requires changing the comments as well. As with most violations of the DRY principle, this will eventually cause problems when someone modifies the code but forgets to update the comments due to time constraints or misperception of the existing comment. As you point out, incorrect comments are actually worse than no comments at all.

Again, commenting to explain *why* something is being done is perfectly viable since it is much more general and doesn't require modification due to every code change, since the reason why will likely remain the same regardless of the implementation. It is explaining *how* something works that tends to cause problems. Since the "how" comments tend to be the kind most often found (in my experience), that was really the whole point I was trying to get across in my original blog entry.

Regards,

Brian

Reply to this Comment

I didn't read all of the comments above but I do this very frequently in my code so I can find various pieces to work on:

<!--- ////////////////////////////////////////////////////////////

Begin some process

//////////////////////////////////////////////////////////// --->

Just so I can visually find a piece of code to work on, since I use a pain old text editor.

Reply to this Comment

In my personal experience, I tend to not use comments that much, but then I regret it when I go back to a piece of code that I wrote months or years ago, as my programming techniques and practices have changed with time -I believe for the better-.
I find acceptable the use of comments for large chunks of code, where I need to quick scan the file and jump to a certain line. I had also used Christopher's type of comments before, as it makes my revisions much faster to find and easier on my eyes.

Reply to this Comment

Jono is correct in asserting that self-documenting code is a myth. It's been around since I first started coding professionally in '89, and I have no doubt in my mind that it pre-dates me. My first job out of college was working on a large system written in C, which was being touted at the time as a self-documenting language. If I ever believed that, I would have abandoned that thought after spending an hour trying to decipher a single line of dense, action-packed code...

Programmers cling to the myth of self-documenting code because, like everyone else, we're lazy. Isn't it enough that we got the code to work, now you want us to tell you what we did? But the better way to think of it is as a way to spare us conversations with other programmers about what it was we were trying to achieve in a particular section of code... Plus, more and more my comments are becoming a helpful aid to myself when I look at some of my own code weeks or months later...

That said, I understand that coding a certain way can minimize the need for comments. One simple thing that programmers often fail to do is use meaningful variable names; it's okay to use i in a for loop, but if i is going to be the number of customers per month, shouldn't it be called numCust or something? Throw me a bone here; don't make me have to scroll up and down to make sense of your code...

I agree with a previous commenter that English is easier to read than code, so in addition to adequate commenting in the code, I also like to see comments when people are checking in code to source control libraries, and when they're closing defect tickets. What was the issue, and what changes were made? Don't just write "Fixed bug", or nothing at all. Once again, it's not a nice thing to do to your fellow programmer trying to figure out your crappy code :)

As for Brian's concern about comments not being kept up to date with code changes, I think that should be part of the check-in process. A programmer I worked with a few years ago got me in the habit of comparing my version of a file with what was previously in the source control library. That has now become the point at which I do any cleanup, or add/modify comments to match my code changes...

Sheldon
p.s. Ben, is it accurate to use a "Life" tag on a discussion about commenting code? According to John Lennon, "life is what happens while you're busy making other plans", so I'm not sure this qualifies :)

Reply to this Comment

@Sheldon,

I threw in the "Life" tag because I felt this also touched on general issues such as those expressed in the Tipping Point.

Reply to this Comment

Hi

I am currently working and supporting an application that is written in javascripts, coldfusion, html, some asp. The code is not readable at all,no design or architecture are available, my task is to some reverse engineering and come up with diagrams. If these guys put good comments and used some conventions, it would be easier for me to understand their code. I really hate coders who can't explain simple things like the input /output of a function, the purpose of the function.

Another thing is there is no modulartiy or code cohesion at all.

Reply to this Comment

The Tipping Point is one of my favourite books, and I had not thought of it the way you have retaionalised it. Interesting!

Oli Hille
Author

Reply to this Comment

While reworking parts of an online shop done by someone who should be happy if I never meet him, I just HAD to dig this one out, expecially since its from 2008, too: http://www.osnews.com/story/19266/WTFs_m
It is such a drag if you have to find out line by line what the guys who made it meant to do - especially if the programming itself is lower level than mine!
AAaarrgh...

Reply to this Comment

Post A Comment

You — Get Out Of My Dreams, Get Into My Comments
Live in the Now
Oops!
Comment Etiquette: Please do not post spam. Please keep the comments on-topic. Please do not post unrelated questions or large chunks of code. And, above all, please be nice to each other - we're trying to have a good conversation here.