Comment Costs And Benefits
Comment Costs And BenefitsThis 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:
This is a comment intended to draw attention to the fact that this page consists entirely of comments about whether or not comments should be used to help explain code, and to request that some code be added to help explain these comments. -FoodmiralAckBar?
Alternatives to comments
Costs
[Actually, it just means that you have to maintain your comments whenever you maintain your code. It adds cost. And there's no way to test a comment for correctness by executing it. Comments communicate only to people. If you can accomplish that communcation through the code, without the comment, there are lots of reasons to do so (this page is full of them)]
"A mismatch between code and comments is valuable information that tells you that work needs to be done in that area. If code is always accompanied with a comment, then each form of expression acts as a kind of logical checksum for the other, thereby improving the reliability of software in the same way that double-entry accounting improves the reliability of bookkeeping. But there is a more general reason for having both comments and code: software has a dual nature - it runs on the CPU and in the human mind, and each of these processors has a different nature. Code is adapted to CPUs and comments are better understood by humans. From a philosophical perspective, code is more deterministic, and comments are more goal-directed. In other words, code tends to be expressed in terms of efficient causation, whereas comments tend towards final causation and purposeful explanation. The identity of each processor implies the type of expression that is appropriate for each. -- TimLee"
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 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
[If some of the conclusions that we are likely to draw from a comment are false ones, I would rather not have that comment at all. Then you're an idiot. All of the inferences given above are invalid; they are the fault of incompetent thinkers, not of the comments. Comments are appropriate to communicate high-level concerns to people. But they often get used to communicate things that would be better communicated through clear, well-factored code. That some comments are bad or misused tells us nothing about comments, and is particularly irrelevant to the point here.]
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
Yes, both. I can say "This function finds an approximation to n!". The function itself might return results that are a bit off.
Unfortunately few systems support mixing SpecificationLanguage? constructs with executable code, but that would arguably be a better approach than using comments for this.
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
-- Uri Guttman
That makes the assumption that the "other person" has the same education, experience or knowledge 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 less-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
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
[Bogus analogy. A UnitTest is can be executed automatically to tell you if your code works or not. All you've proved by writing a lengthy comment about something is that you understood it well enough to write a lengthy comment about it--that says nothing about the quality of the accompanying code. Some people seem to rely too much on comments precisely because they AREN'T good at producing quality code. There are legitimate reasons to use them, but comments are often a CodeSmell.]
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. Not so for embedded systems that use cross-compilers and remote debugging - which most do.
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? Better names would be more helpful, in my opinion.
To answer Ron, a number of (poor) embedded C compilers / linkers only use the first 32 or so characters in global identifiers. Also, to reduce the possibility of name clashes, many shops have the convention of putting the defining module name in each global identifier, reducing the useful size to about 20 to 25 chars. Now, the length of method/function names really becomes an issue.
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 empirical 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
when code and comments disagree, the comments are always wrong -- or are they?
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 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.
For another example, 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.''
<sarcasm> If you can't figure out what the assumed access pattern is, just by reading the code, I'm certainly not going to tell you. </sarcasm>
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 WorkArounds 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 whys 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 InterIntegratedCircuit 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
Is this an example of need for comments or a need for refactoring? For the parts in C, any refactoring not involving inheritance can be applied. Although one could simulate inheritance, I think in this case that the cure may be worse than the disease. As for the assembly portions, carefully review what really needs to be done in assembly and port the remainder to C. Also, if one has a really good assembler, assembly can rival C in clarity (but what I would qualify as a really good assembler is very rare). -- WayneMack
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 believe 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.
ZwMakeTemporaryObject is a Win32 Kernel Mode (Driver) function. Despite its name, it is documented as a function that changes the attributes of an object to make it temporary. Perhaps ZwMakeObjectTemporary would have been a better name...?
(* 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
On the other hand, it might mean you haven't communicated clearly what you are talking about. Comments are for communication to people - other team members, future maintainers, yourself three months from now (or three weeks!). But using comments has disadvantages which you can avoid if you just write clear, expressive code instead. If the code is unclear you should fix the code. Use comments only as your last resort, or to express things the code can not clearly express.
My point above must be getting missed - put another way, if I was a math major and used clearly (but mathematically) named identifiers in my code, someone with less math experience may not get what I am doing because they do not understand the nomenclature (yes, some developers do not understand "Epsilon" in the context of doing floating point operations). Comments, when presented in a natural language, can bridge this gap. If English is the baseline, then we can all understand clear and expressive English. Naming conventions (clear and expressive code) does not have a common baseline that I am aware of, and I have seen lots of code in my day.
-- JamesTwine
IDE's should have a simple toggle option to make the code more visible if the comments are taking up too much real estate.
Some do. Both Eclipse 3.1.x and Microsoft Visual Studio 2005 allow you to either collapse comments to show only a single line, or expand to display the full text. Nice, this. -- DaveVoorhis
Wrong. A SIMPLE TOGGLE option means you click one button and all comments on the whole page disappear/reappear. Shuffling through pages and clicking each plus/minus sign to non-inlined comments and still having a comment line visible is so lame it isn't worth mentioning.
You are right that a SIMPLE TOGGLE option means you click one button and all comments on the whole page disappear/reappear. You are WRONG when you think Visual Studio doesn't have that. It does - Ctrl+M, L. It's true that Eclipse 3.1 is a bit lame - you can only expand all (using Ctrl+Numpad*), you can't collapse all. Reading between the lines of http://download.eclipse.org/eclipse/downloads/drops/S-3.2M1-200508111530/eclipse-news-M1.html suggests Eclipse 3.2 will fix this. -- DaveVoorhis
See WellCommentedCode, ToDo, FixmeComment, HeadlinesTechnique
EditText of this page
(last edited October 14, 2014)
or FindPage with title or text search