Comment Costs And Benefits

This is yet another attempt to reconcile various attitudes towards code comments. See also MethodCommenting,ToNeedComments, WellCommentedCode, WellFactoredCode, CommentingChallenge, StripExcessiveComments, TreatCommentsWithSuspicion, the various ExtremeProgramming pages, etc. I want to list the costs and benefits which comments have in a relatively neutral way, without actually coming out and saying whether comments are a good thing.

What I'm seeking here is some model of what comments' strengths and weaknesses are, what their role should be, when they should be supplanted by other tools. Later... I find I can't do that without some notion of what the alternatives are, so I'll start with a list:

alternatives to comments

Please add others, or other examples. Meanwhile, the main show...
Costs

Programming is time-consuming. I find (and this may be a purely personal idiosyncrasy) that I write the comment first. By the time I've expressed what I'm going to do in English prose, spitting it out in code is trivial. This means that the comment captures my thought process in designing the code, alternatives considered and discarded (and why), and many other things that are not expressed in code. For me, doing it this way allows me to capture useful information from the design process that would otherwise be discarded. -- JimPerry

I worked at a company where all functions had big block-style comments at the top. A lot of the modules were state machines with a bunch of small action routines for state transitions. If it weren't for the comments, you could easily fit the entire modules within a couple pages of screen space. For state machines, it's important to quickly scan the code to understand the overall flow of the system. The comments made this cumbersome. I never got any values from the comments; they simply repeated things that were obvious from the code, and they often became inaccurate. -- SteveHowell

Hang on here. Just because comments can get out of date doesn't mean that comments are bad - it just means that you have to write GOOD comments. The argument that comments can go out of date so you shouldn't write comments is similar to the argument that because executable code can crash the machine it's run on you shouldn't write executable code! -- MattCline?

About four years ago I worked for a company where the engineering manager banned comments, despite most of the engineers being strongly in favour of commenting code (seriously!). The manager's arguments was "the comments might be wrong, so they aren't worth the risk". I took his flawed axiom and used some simple logic. Well, we might get the code wrong, so we should stop coding too. And I might go into the wrong office tomorrow morning, so I'll stay in bed all day instead. I quit soon afterwards. -- Jim McCluskey?

I spent an hour tracking down a bug because I trusted a method name. -- JohnFarrell

Has anyone ever observed this? Frankly I've encountered very few programmers willing to write comments, and none who prefer commenting to writing good code. -- JimPerry

I have observed this. Bad code tends to grow comments because it is hard to understand and people become afraid to change it. Many programmers will comment bad code rather than repair it. -- WayneMack

I have observed this too. (Similar forces are at work when user documentation grows to compensate for poor interface design. Programmers are reluctant to change the interface). -- JamesCrook

I have also seen this. When I see code with great big boilerplate headers for every method I think "Uh oh". A lot of the time the code inside is either written the way the programmer hoped it would work (as described in the method header), or it's written with as few characters as possible as if the explanation in the method header excused them from writing legible code. And then there are the comments written to describe the clever trick that makes the code work. Those are a sure give away that the code is rotten (see KillYourDarlings). -- Phil Goodwin

The reduced precision of comments is their strongest point. Reduced precision can mean greater abstraction, and abstraction is one of the programmer's best friends. Comments can express things at a higher level than the code, AND they can illustrate WHY code is doing something, not just WHAT it's doing. -- MattCline?

I have observed this more than once. -- RobHarwood

Is that it? I'm tempted to add, "They say nothing which the code itself doesn't say", but that's only a drawback because of the other factors.

If comments say nothing that code doesn't say, then the comments are poorly written. Many of these so-called disadvantages to comments are, in fact, symptoms of *bad* comments! But just because comments can go bad doesn't mean they're bad by nature. -- MattCline?


Benefits

Do you mean "precise" or "concise" here? Because comments are (ideally) at a higher level of abstraction than code, they should be able to express things more concisely, but not necessarily more precisely... -- MattCline?

But see the remarks in ToNeedComments. The code itself can do a large part of this. Where it can, aren't the comments redundant? -- RonJeffries

Could you expand on that? ToNeedComments is pretty big. Most of the points above are of the form "comments are more XXX than code" so it seems peculiar on the face of it to say the code can do the same. -- JimPerry

If code is difficult to explain to another person, that's a sign it should be rewritten. And then throw away the comment and keep the rewritten code. Comment the rewritten code to add information the code itself doesn't provide. -- RonJeffries

That makes the assumption that the "other person" is on the same educational and/or experience level as the person that wrote the code. This is not always the case. Also, just because the code has been refactored and/or rewritten, that does not automatically mean that it will clear or intuitive to everyone that reads it. Comments serve as a (more or less) "plain English" way of explaining code or what the code is trying to do (which may be more important than what the code is actually doing). My experience has shown this to be of value when lesser-experienced staff ends up reading or doing maintainence work on code; they may learn what the code is doing by reading the comments. While it is a valid argument that comments easily get out-of-date, as already mentioned; this is a fault with the developer(s), not the comments (or the act of commenting) itself. -- JamesTwine

Ok - I don't feel I'm doing so well here. The points are not so orthogonal or clear. I'll leave it at that and hope someone else can improve or rewrite it. You're doing brilliantly. Keep up the good work!.


I especially like "Comments discipline the mind". Teaching tests your understanding of a subject. Comments as tutorial can demonstrate your understanding of the goal, regardless of whether you successfully implemented it. -- WayneCarson

A lot of these benefits are at best intangible. In particular, my customers expect me to discipline my mind on my own time. On their clock they are looking for high-quality, maintainable functionality at a predictable cost they can afford. -- RonJeffries

The idea here is that writing a comment is similar to running a UnitTest. It's a way of checking the quality of a particular piece of code, rather than a form of training for the programmer. -- DaveHarris

How do we connect some of these goods back to the point of the development? -- RonJeffries

Good question. I definitely want to come onto that. Writing that list emphasized (to me) some of the roles of comments that would be better taken on by other tools. For example, perhaps the "explaining the code" role is better done by CodeReview(s) or by turning to the colleague at the desk next to you and actually explaining it to them.

That said, I do want to distinguish between the ideal working environment, where all necessary tools are available, and the actual environments that some of us are stuck with. -- DaveHarris


Can anyone report on a project where the length of the method names was actually a problem? -- RonJeffries

It's always a problem once they get over 20 or 30 characters long. The code just gets too unwieldy. No expression will fit on a single line. -- DaveHarris

In embedded systems it matters a lot, as it limits the amount of code you can debug.

I have run into linker errors involving the length of method names. Although each programmer had a reasonable 20-character name, when they all were concatenated due to pointers to functions taking overloaded class methods with classes as arguments, we easily get to 300-character symbol names which the current Microsoft linker cannot handle (as of 2004). Where does this madness stop?!? This example is from the C++ STL (Standard Template Library)! -- GreggTracton?

I also see problems with variable names that vary by only a few characters or by the order of the words in the name. Comments are a good way to point out these slippery slopes. -- GreggTracton?


On the redundancy of comments.... My experience is that it takes longer to figure out something from the code than it does to read a comment. My loaded language reflects that - reading code is "figuring out" while reading comments is "reading." At the very basic word level, I find an English sentence with spaces easier to read than a VeryLongBumpyCaseMethodNameLikeThis. When you have 4 or 7 lines full of expressions involving such names, where each expression typically doesn't fit on a single line, and where each piece does such a small part of the job that you have to keep many of them in your mind at once to grok the big picture of what is really going on - then the difference is magnified.

If there is such a difference in readability, how big can we allow it to grow? If it takes, say 5 seconds to understand an English comment and 45 seconds to figure out some code, is that enough to justify the comment's presence, or is it still redundant? If not 5/45, what ratio would justify the comment? Are the 5/45 numbers plausible - does anyone have any empircal measurements?

-- DaveHarris

When I need to change the code, I find it gets done faster if I ignore the comments and read the code. That way I avoid errors, and understand what actually is going on.

I agree that it seems easier to read comments than code, but it's more productive to read code than comments.

--EricUlevik

When you're concentrating on a particular bit of code, you need to read that code, not just the comments attached to it. But when you're concentrating on one bit of code and need to understand another, you don't always need the very precise understanding that reading its code would give you. Skimming the comments can be much better. -- GarethMcCaughan

One of the most time consuming problems is when the code and the comments differ. I have spent a lot of time investigating things only to find the comments were incorrect. This often diverts time from finding the actual problem I am interested in. -- WayneMack

The problem with comments is, of course, that in a disagreement with the code they are always incorrect; tautologically so. (See the "less reliable than the code" heading above.)

Actually, I'm not so sure. I believe it is possible for the comments to be 'correct' while the code is 'incorrect'. Of course it depends on whether you use the word 'correct' to mean 'how things actually behave' or 'how things are supposed to behave (to work properly)'. For instance, if I read a comment that says "this method must be synchronized", and the code isn't synchronized, then something's wrong here, but it MIGHT be the code that's wrong not the comment.

''One would like to know why it needs to be synchronized. Duh, yes, multiple threads, but what are the threads and what is the assumed access pattern? Very important in understanding a system.''

For example, if there is a customer requirement, and an exact quote of what the customer said is embedded in the comments. If there is a bug and the software doesn't do that, the comment is correct, the code is incorrect.


On some of the projects I've worked, System Engineers write requirements for the Software Developers to implement. Comments aid in demonstrating that the Software Developer understands the requirements.

This is sort of covered by several of the above benefits -- WayneCarson


One area where I still find comments helpful is in documenting work arounds for third party code that does not work as expected. For example, a function call that simply does not work and needs to be replaced with a more convoluted work around. The comment serves as a "bad smell," but one that cannot be currently resolved. -- WayneMack

I'd like to add an enthusiastic second to this one... Any time I have to do something Genuinely Strange to work around a problem, I aspire to always explain the why's and wherefores. I also try to include some debug code that will test to ensure that the workaround is still needed (though this doesn't happen as often as I'd like).

On the other hand, I have yet to be burned by a misleading comment. Once bitten and all that.

-- Mark Storer


Moved from ToNeedComments

I've had the luxury of having written good software with teams with a strong comment focus, and with a team whose focus is to write code so simple and so clear as to need few comments. In my actual experience, the latter works better. Communication and code quality really are enhanced by this practice, not degraded.

I didn't believe it going in; I tried it; I learned something. -- RonJeffries

But even in the very simple CommentExample, the code was not clear, because it didn't answer common questions a developer would have. This is imho the primary role of comments. -- AnonymousDonor

I actually use such practices, and have for years. I also use comments. I don't know what's left to try, aside from writing the same code and leaving out the comments, but I know that when I do that I find it to be less informative and to require more effort to maintain. The options are not just "poorly-decomposed code with comments to make up for it" and "well-decomposed code without comments"; I prefer "well-decomposed code with comments".

"Don't comment bad code - rewrite it" is a very old programmer's maxim. I still find, when reading code I consider well commented, that I skip the code and just read the comments. -- DaveHarris

Even in following such admirable patterns there is still benefit to well-crafted natural-language expression of what code is doing. CommentCostsAndBenefits touches well on some of the reasons why. Is anyone saying that you shouldn't document your code at all? Perhaps not in so many words, but deprecating language about comments and insinuations that comments are used largely to salvage poorly-written code can have a chilling effect, to the point where comments aren't used where they are in fact "needed" (perhaps on the class, or groups of methods, if not on the methods). -- JimPerry

I think this is largely about balance; I suspect people are attributing positions to each other that are more extreme than those actually held, and we're bouncing around between extremes. Fighting past wars rather than the current one. Also I suspect the balance depends on the programming language and environment used - Smalltalk typically needing fewer comments than Java, and Java fewer than assembler. Lack of shared experience makes it harder to see the other fellows point of view. The only way forward (in my view) is to make this stuff explicit. -- DaveHarris


The first statement (we specifically deprecate...) is uncontroversial, since I haven't seen anyone advocate that programmers should write unclear source code and then garnish it with comments. (Surely that's not what you meant by your earlier pro-comment bias). If the source code can be made clearer, by all means make it so (and then add comments that make it even clearer).

Perhaps this is just one of those half-empty/half-full things, but I fail to see how comment avoidance can be "fruitful". All the factors driving code clarity and refactoring still apply, so comments over and above those provide even more and better communication. It doesn't take much time to write a comment, and they needn't interfere with reading the source code, so I don't see much cost. -- JimPerry

Programmers who can't write clear code are unlikely to produce useful comments. And useless comments definitely have a cost. Every developer who sees them will have to read them or read around them. It's more productive and easier to teach programmers to write clear code than to teach them to comment well. -- KevinCline


One of my current projects involves deciphering CeeLanguage and AssemblyLanguage code written for small devices and which implements bit-level and byte-level IIC (InterIntegratedCircuit or EyeSquaredCee) protocol drivers. There are ISRs that are essentially uncommented because all the engineers that worked on this, 8 years ago, knew what they'd built and how it would all work together.

A large amount of time has been spent digging up original authors and poring over project and debug docs trying to get a handle on why a particular delay constant was used, why interrupts were disabled at a certain point, and why ISRs (which should do something simple and leave) have become two-page state machines.

Comments strategically placed in the code to explain some of the (occasionally heinous) compromises would have saved me a month at least.

My vote is for lucid, expository comments. -- GarryHamilton

I totally agree, but I have the urge to explicitly state that the nature of AssemblyLanguage greatly increases the need for comments. -- JoeWeaver

And I would concur. So at what point along the ladder of languages does the language form and syntax itself assume the burden of comments? -- gh


No Comment /* ie no comment on this article */ -- Malek BADI


Well-written code makes it easy to see what is being done. In the minority of cases where it isn't obvious, good comments explain why it is being done. Works for me... -- DanMuller


One other thing... while some suggest that descriptive method and identifier names remove the need for comments (see IdentifiersAreComments and similar topics), there are situations where you are using a 3rd party Library or platform-specific SDK/API that might not have descriptive names. Again, a place where Comments are beneficial. For example, ZwMakeTemporaryObject... Does this method create a "temporary object", or mark an existing object as "temporary"? What kind of "object" does it create/change?

Going along with what I said above: I beleive it is incorrect to assume that other developers have the same understanding/experience/education as you do. As such, it is incorrect to assume that just because the code is clear to you, it will be clear to others as well*. I am sure someone thought that ZwMakeTemporaryObject was a completely clear identifier.

(*As I have said to someone in the past, just because you do not know what I am talking about, that does not mean that I do not.)

-- JamesTwine


see WellCommentedCode


EditText of this page (last edited April 7, 2004)
FindPage by browsing or searching

This page mirrored in WikiPagesAboutRefactoring as of July 17, 2004