Not Commenting And The Tipping Point Of Poor Programming

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.

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.

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.

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.

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."

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!

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.

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. ;-)

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".

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.

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.

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.

<!---
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 --->

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.

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.

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!

"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.

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

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 :)

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

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.

@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

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.

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.

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 :)

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.

I know that CFSCRIPT supports line comments.

I really wish regular CFML did as well --- that would be awesome!!

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

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...