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
[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)]
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. 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.]
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?
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
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
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.
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?
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.
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>
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 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
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 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 inheritence 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.)
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.
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 (touched by ColinWright)
see WellCommentedCode ToDo FixmeComment
This page mirrored in WikiPagesAboutRefactoring as of April 29, 2006