Comment Costs And Benefits

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

• Embed the information from comments into variable, method and class names. Refactor the code until this can be done. IdentifiersAreComments.
• ProjectLore: leave the information in the minds of the programmers.
• ??? : leave the information in a dusty 3 ring binder or other separate files.
• Use tools to extract the information from the source, e.g.:
  • Source-code browsers.
  • UnitTests.
• Use assertions (ReplaceCommentWithAssertion, AssertionsAsComments).

• They take time to write. In fact, good comments are very hard to write. You need to think carefully both about what you are doing, and also about who your audience is and what they will already know. This is time consuming.

• They take up screen real estate. This is especially true for some verbose styles - for example where every comment has blank lines which make it at least 3 lines long. It's a problem because the comments push the real code off the screen, which means you must exercise your short-term memory more when trying to understand it. [Of course, a silly coding standard that mandates horrendous block comments like this isn't a good reason to not use comments. Better to change the standard.]

• They are less reliable than the code itself. Comments can get out of sync with the code if people change the code without updating the comments. Then anyone reading the comments will be mislead. Even if they are in sync, you can never be sure of that, so you have to read the code itself to make sure anyway. [This is far often more true of offline documentation than of in-line comments; with comments taht are inline it is easier to enforceIfYouChangeTheCodeChangeTheComment]

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?

• Adding comments can be 'high risk': I've spent hours tracking down a bug because I trusted a comment that someone other than the original author added after the fact. The code was complex, so I trusted the comment - my mistake, but I would hesitate to call all comments 'low-risk'.

• They encourage bad code. The idea here is that people will write bad code and then comment it, rather than write good code.

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

• They are less precise than code. It's very difficult to write "plain English" as unambiguously as code. This is because it isn't limited, etc. Put another way: comments lie. -- RonJeffries

• Programmers ignore them. Since comments are frequently out of date, experienced programmers ignore them as a reflex. (This is based on my experience with mentoring a programmer for a week on some code I wrote. Despite my repeated reminders, he always skipped right passed the comments and to the code. I don't know if this is true overall. -- JimLittle)

• They give a false sense of security. If my code is littered with comments, it must be:
  • Working.
  • Understandable, even if it's not necessarily working.
  • Easy to debug, even if it's not really understandable.
  • Maintainable, even if... (You get the idea)

I have observed this more than once. -- RobHarwood

• They reduce the clarity of well-expressed code. Well-factored code with good names is clearer and easier to read than the same code with comments. The comments end up being redundant. At this point, they should be removed. (Note that this implies that if comments add to clarity, the code is poorly expressed and could use refactoring.)

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?

• Plain English is easier to read than code. This is because it isn't limited to the rather simple and rigid abilities of computer parsers. English (or any natural language) is more expressive than any programming language.

• Comments can be more precise than code. They can include mathematical/logical notions like "for-all", "there-exists" and so forth. Routine pre- and post-conditions are sometimes easier to express as comments than as executable assertions.

• Comments ease comprehension by collecting information into one place. For example, by explaining the context in which a routine will be called.

• Comments can be at a higher level of abstraction than the code they document. When this is true, the comments act as a specification for the code. (You could delete the code itself, and later reproduce it from just the comments.) This can make them easier to understand. AssemblyLanguage programmers sometimes use C language to comment their code.

• comments can express things that cannot otherwise be clearly expressed in the source language. At a higher level than the "C commenting Assembly", how do you express that "This code licensed under the LGPL", "Jane Doe requested this feature", or "see "Rate Monotonic Scheduling" article by David B. Stewart and Michael Barr in _Embedded Systems Programming_ 2002-03 for a proof that this algorithm is optimal" in any ProgrammingLanguage outside of comments ?

• Comments are shorter than the code they document. This means you can scan code quicker by just reading the comments until you get to the bit you are interested in.

• Comments factor out explanations. One alternative to comments is longer class, method and variable names. But these names are used far more often, so you actually waste screen real estate (i.e. short-term memory) overall. A comment can explain the meaning once, clearly and fully, and then the variable name (or whatever) only has to remind you.

• Comments are persistent. This is in contrast to ProjectLore, information kept in the minds of your programmers. Lore is liable to be lost when those programmers resign or get run over by a bus.

• Comments are accessible. You can discover information from comments very easily, eg without having to interrupt someone else. They are right there in the code where they're needed. (This is another anti-ProjectLore point.)

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

• Requested Expansion. Comments are accessible: code can be accessible too. Comments are persistent: code is even more persistent and tracks changes automatically. Comments factor out explanations: well-written code factors out explanations and improves quality at the same time. Comments are shorter than the code they document: this is unproven at best. Comments can be more precise than code: this seems to me to be false; code is precise, natural language isn't. -- RonJeffries

• Code is precise about WHAT is happening; (good) comments are precise about the WHY. Simple example (assuming a C programming environment): if you have a pointer as function argument, you don't know if this is so because the pointed-to object will be modified, or if there are performance considerations behind this. A more expressive programming language can say more about the WHY, but there will always be something you can't express in a programming language (unless you work with a HAL 9000). -- FreddyTheCat? [Re: "[if] a pointed-to object will be modified", in C, use const; I hate this use of comments. It's less powerful than proper use of const. -- SunirShah?] [const is good but still insufficient; it doesn't help to differentiate between output-only and update (input-output) parameters]

• Comments discipline the mind. Writing a comment is a way of testing your ability to explain the code.

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

• Comments are easier to skim-read than code. When you're looking through a program, you look briefly at a lot of stuff you don't bother to read properly, by way of orientation. If the stuff is commented well, you can look at the comments instead of the code, saving time and thus making your reading more fluent. -- GarethMcCaughan

• Comments don't affect execution speed. (I just tossed this one in - rarely a factor in practice.) It is important. When execution speed is important, and you've just written some 'clever code' (for 'clever' read 'incomprehensible') to achieve speed, it would be very sad indeed if comments were costly....

• Comments are low risk changes. Comments are highly unlikely to change the operation of the software, even when the code is misunderstood and the comments are wrong. I have seen some rare instances where an unterminated comment has broken working code and it is a real pain to find, but then again this is very rare.

• Comments can document rejected code. This is hinted at above, in the "comments take time to write" paragraphs. A comment can discuss the design decisions made in coming to write the code that's actually there. So if the 'obvious' solution has been rejected as incorrect (because it's too slow, or causes conflicts with some other subsystem), the reason for the actual implementation can be documented in the comments. BlindAlley.

• Comments document the intent of the code. This can clarify the purpose of tricky code (but refactoring the code would be better). Also, if a change is made to the code so that the code no longer executes the intent, then having a redundant comment will allow the programmer to restore the code (but having automated UnitTests would be better).

• Comments document unexpected complexity. I'm sure we've all seen a function with a misleading name, which takes a strange set of parameters, or returns some bizarre value on success (and that can't be changed). A good comment next to the function call explaining that the call is indeed correct can save a lot of developer time if a coder sees this code and is tempted to "fix" it. Ditto with certain language features that can produce code that looks wrong.

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

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?

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.

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

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

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

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

This page mirrored in WikiPagesAboutRefactoring as of July 17, 2004