To Need Comments
To Need CommentsRefactor the code properly and you won't need comments.
One consequence of refactoring is that it introduces a new method name. That name should shoulder a lot of the information burden that might have required a comment. Especially if the original method was long.
Are you saying that having well-factored code and having commented code are mutually exclusive?
In XP, it's a matter of focus. Our rule is that a comment is a sign that the code is not finished. When we see a method that needs a comment, our rule doesn't let us stop with the comment -- it leads us to focus on improving the code. And since we practice CollectiveCodeOwnership, anybody is free to clarify code if it isn't clear enough.
If you write and refactor code with a focus on minimizing comments, less than 1% of your methods will support non-redundant comments. And teams with a strong oral tradition (enforced in XP with PairProgramming) will not suffer in any way from the absence of those redundant comments.
We might comment upon a special algorithm, or a necessary but obscure optimization. See MethodCommenting for some good examples.
ExtremeProgramming is not CowboyCoding. Quite the contrary - most cowboy programmers will never make the XP cut. Communication is one of the XP values, and communicating with the code is the best way to produce a good product.
I've been waiting for someone to clarify something about "method comments" versus other sorts of comments; I suspect this may have some relation to the particular language or development environment. It's true that as methods are factored into smaller and smaller units of functionality then there's less per method to comment on, certainly compared to an assembly-language subroutine. (Which is not to say there isn't meaningful information to communicate even in such methods, but that's another matter). However, there's still a communication problem which can manifest itself as not seeing the forest for the trees. Natural language prose documentation can help that, and comments have the advantage of being bound to the code itself. They may be attached, if not to single methods, to the class, or to an interface, or to a method which acts as gatekeeper for a cooperating group of objects and methods. Of course, it may also be in some completely external form, or somewhere in between as in LiterateProgramming, though that can be harder to maintain.
Yes, definitely. In XP we strongly recommend class comments, which give that overview that can be hard to pick up in browsing. We also find that browsing users of classes, and UnitTests, also gives a really good view of how classes are intended to be used. The advantage to actual uses over comments is that they evolve to stay correct. -- RonJeffries
Comments getting out of synch with the code they document is a symptom of poor standards or practice. Reading existing code tells you how classes ARE used, not how they are INTENDED to be used. Far better to adhere to an explicitly documented/designed interface/contract. -- JimPerry
I am not sure about your distinction between the way classes "ARE used" and "INTENDED to be used." Classes need to work in the way they are used and it really does not matter what someone long ago intended. Lower level classes are intended to support higher level features, not dictate what higher level features are to be provided. It is far better to adapt the interface to what is needed, than to use work arounds because of some existing "contract."
I think that the actual use is probably a darned sight more important than the intended use. If things were intended one way, but are generally used the other way, then the author can either give in to the inevitable and adjust his intention or else can crusade against the variation in the actual. Something has to change, and so indeed the code is unfinished. -- TimOttinger
I believe that the intended use is at the core of any public interface. See DesignByContract. If someone abuses a class by using it in a way it wasn't INTENDED to be used, like, for example, calling 'imageLoader.LoadImage?("randomBinaryData.bin", ImageFormat?.Raw)' to load non-image data because it's convenient, that just makes the code harder to understand and can cause problems later on when the image loading code is changed (eg. by backing it with a different image decoding library that still serves the INTENDED purpose, but fails with its ACTUAL use -- MarkusEwald?
Elsewhere on this Wiki I've read XP advocates observe that they don't in fact use class comments as often as they "should". My suspicion is that this is related to the cultural deprecation of comments in general (that's just a suspicion, of course, but reflects my essential issue with this whole business of "rules" about "we don't use comments").
Jim, we don't have rules like "we don't use comments". We have a specific set of coding standards that focus on code clarity independent of comments. Comments are our last resort, not the first. We use them where we find they are needed. Those standards, by our thoughtful analysis, result in code which needs a very low frequency of MethodCommenting.
"In general, we do not comment our methods. Beck teaches that a comment is used to indicate that a method is not yet finished. That's how we use them." Perhaps I'm just missing something but my paraphrase doesn't seem that far off. However, I think we've now completed the circle and are back to what it means ToNeedComments (or not). -- JimPerry
I can well believe that environment/language makes a difference, but I'd like to see that defended: I've heard partisans of every language from COBOL to FORTH describe their language as self-documenting. I don't see any obvious reason why Smalltalk would require fewer comments than Java, for instance, though in both cases the issue of shrinking methods raises the question of where to hang comments to make them useful. -- JimPerry
Actually Smalltalk is not my pet language - I'm primarily a Java programmer at the moment. I believe in static typing. I don't so much think Java needs fewer comments - if anything, Java's manifest type declarations ought to eliminate a few more - but that Smalltalk code is more amenable to refactoring. This is because of all the overhead and syntactic noise that you need in Java to declare a new method. You need its return type, the type of all its arguments, a list of the exceptions thrown, as well as the usual brackets, method and argument names. Smalltalk can handle lots of very small methods more nicely than Java.
Java code containing so much static type information makes it harder to refactor by hand, but makes it easier to perform correct automated refactorings. Since good tools are available (such as EclipseIde), this is not a problem in practice. EclipseIde also leverages the static type information to provide great browsing support ("browsing" in the Smalltalk sense, navigating through your code like hypertext). I've come to believe that the only good justification for statically-typed languages such as Java today, is that the static type information is useful to get this level of automated tool support. --WylieGarvin
Smalltalk development environments also tend to be better. Eg it can be easier to find the senders of a message in Smalltalk, which reduces the need to document the context in which the method is called. -- DaveHarris
We do rely on our oral tradition, to a large degree, for knowledge of how groups of classes interact. A property of XP as it is practiced today is that there are very few permanent artifacts outside the code. CRC sessions are not persistent. For ProgrammingInTheLarge? or ProgrammingInTheLong?, we'll need to add some practices, as we have mentioned elsewhere. A team of 10 doesn't need UML diagrams, in our experience, so we don't do 'em. -- RonJeffries
Let me try this from another angle. Imagine what a program would have to be like so that it didn't need comments. (Or, if you can't reach that far ... to need far fewer comments than most programs need.) Things like ...
Just for a few minutes ... try to imagine that it were true ...
(Bold names above are KentBeck pattern names from Smalltalk Best Practices Patterns.)
What it means for code to need comments is subjective. Obviously code doesn't need comments to work, if it does; and if it doesn't, comments won't help make it work. By the same token, code doesn't need meaningful names, indentation, and so on, either. Those things are tools used for communication, from the writer of the code to its human reader, and comments are another such tool, one which supplements rather than replacing or being replaced by the others.
A poorly-written manual may be somewhat improved by a good diagram, but that is not the only function of diagrams. The most clearly-written prose document may yet be improved by a diagram, and the best documents balance the tools of prose, graphics, organization, visual layout, indexing, etc. Certainly we don't take the presence of diagrams in a book, in general, as an indication that the prose or typesetting should be reworked until the diagrams are no longer needed.
Diagrams are a good example. XP has essentially no diagrams, and I miss them. My thought processes are highly geometric and diagrams communicate to me, and work for me, in a way that code and CRC do not. However, is the analogy between a diagram and a comment close? I'm not so sure. -- RonJeffries
The analogy is intended to be comment::source code is as diagram::prose document, it supplements, summarizes, restates, whatever. Your point about diagrams in XP strikes me as closer to the heart of this discussion: for some of us, apparently, prose comments supplement and enhance the more formal symbolic code in the same sort of way that a diagram communicates to the visually-oriented. -- JimPerry
Sometimes comments are useful for documenting incomplete or otherwise unclear code, until such time as it can be completed or clarified; but those are not the only uses for comments. Some of those other uses have been discussed in MethodCommenting, but some basics are to allow the reader to quickly grasp what the code does (at a greater level than that conveyed by the method/class name, but lower than the full detail of the code itself), and more importantly why it does so, or why it does what it does rather than something else. The benefits of such comments are over and above any attained through factoring, formatting, name selection, and so forth.
I would venture that for any reasonably-sized chunk of code, commentless but factored and refactored to a gleaming perfection, it could still be improved, to my taste, by adding the occasional well-crafted comment. Would it need such comments? That depends on what one means, but it would, in my opinion, be more rapidly comprehensible to someone unfamiliar with the code in question (which includes the original author after a hiatus of a few months), and probably be more comprehensible on a daily basis to regular maintainers (almost certainly no less so), than the same code without the comments. -- JimPerry
I worked with a fellow once who refused to comment, indent or even carriage return at reasonable places. I made him sit and watch me refactor one particularly crucial piece of code until we had something even KentBeck would like. I found lots of duplication and irregularities, but nothing fatally wrong with the original, much to my amazement.
"What do you think?" I asked.
"I think we just wasted an hour," he said, "It still does the same thing."
"You're right" I said as I reverted to his original. If he wasn't going to admit it looked better, I wasn't going to let him enjoy looking at it.
I ran into him at a conference a few months later. He said he had tried formatting code on his own and kinda liked it. Ahh. Small successes. There is a moral: If you don't like looking at your code you are probably not writing it well. -- WardCunningham
Ward, I want to be as wise and as patient as you are, and I want it now! -- RonJeffries
However, it is true that English sentences are often more readable than veryLongBumpyCaseMethodNamesLikeThis.
I know some shops have required comments: very verbose, multi-line things before every method. It's impossible to convince some people that such bureaucracy doesn't help - but I think everyone here understands.
I take it XP is opposed to LiterateProgramming, as seen for example in JavaDoc? -- DaveHarris
Not at all. LiterateProgramming is part of our toolkit. What we have found on C3, however, has been
Your final paragraph seems to contradict your first :-)
I don't see the contradiction. We use our tools where they help us, and not where they don't. No one read the literate programs. Investing in more would be wasteful. Meanwhile I believe in them and like writing them. But in XP we don't do what we believe, we do what our measurements tell us. -- RonJeffries
"They do not get updated" - I'd regard that unacceptable programming practice.
The XP practice is to do what works, and not what doesn't. Since our literate programs are not used, we decided that updating them was wasteful. -- RonJeffries
It's avoidable if you have the right culture. Maybe XP just doesn't think it was important enough to bother? -- DaveHarris
Exactly. A key aspect of XP is that we look at our practices and enhance them continually. We drop practices that don't help us. The literate programs, on our project, didn't help us. We consider them to be part of our toolkit because we would, and will, use them when we need to communicate to a wider audience. -- RonJeffries
I think your "sitting with some experts" comment shows a limitation of XP. You need the experts on hand. If you're producing code which will get used by people outside of your shop, then the comments become more important. XP is very much about ProgrammingInTheSmall?. ProgrammingInTheLarge? is a different context which needs different patterns. JavaDoc, for example, is used by programmers inside Sun to create documentation for the thousands of programmers outside of Sun. I rarely look at the Sun source code; I just use and rely on their extracted comments. -- DaveHarris
No question, XP is very much about programming in small, highly communicative groups. We make no claims from experience for how it translates to larger groups, more distributed groups, or groups that don't talk to each other.
On such projects I would certainly want more LiterateProgramming. I would certainly want more comments, if the code didn't communicate sufficiently. And some other practices would surely have to be beefed up. Just which ones, and how, will have to wait until someone expert in XP is dragged, kicking and screaming, into a larger less communicative project. -- RonJeffries
Having been involved for several years in ProgrammingInTheLarge? (10s of programmers, 100s of KLOC, Ada), I can't see eliminating all comments. Assuming the same level of competency and domain understanding (which is unlikely), you would need a VERY strong and common philosophy among the developers, or you have to document each developers philosophy.
How do comments help in large programs? I can see other forms of documentation that may substitute for direct communication, but fail to see the value for comments interspersed amongst the code.
It's best to clarify what "large" means. Think tens to hundreds of thousands of KLOCs developed by tens of thousands of engineers worldwide over decades. Without a working ouija board direct communication with some developers is impossible, and the thousands who were laid off aren't going to be of much help either. The best practices that are easy with a small good team go out the window as political forces in widely disparate groups take hold. Complexity rises to the point where the technical leadership loses sight of the whole picture and sustainers cause as much damage as they fix. When the number of small documents produced by teams of a few people each reaches into the hundreds of thousands and all are out of date, you need any useful information you can get. It's in this where inline comments which give insight into "why" right where something is happening versus the code which only explains "how" that makes the difference. Think of it as a dual to localizing variables to the scope in which they are used.
That said, even in the small inline comments can be very useful. While recently reading some Altivec code an inline comment noted memory accesses were intentionally done out of order as it allows for higher memory bandwidth on a particular processor implementation. The overview inline allowed the reader to know why it was done in the abstract and had a pointer to the reference manuals for more detailed information if needed. Had those not been there one might have looked at an abstract instruction reference and miss out on the optimization details for a particular instance of the processor. Reflecting this back to scale, when you can get a 30% performance improvement at the system level through such highly specific optimizations and the system costs $10M, you have $3M to spend on this kind of coding before your competitors who won't do this can break even with you. Leaving information right at the place where it is needed for the person who has to maintain or extend the code is most welcome.
Finally, in teams where people can't get a few lines of text right for a few lines of code, there won't be any other correct documentation or refactoring to fill in the gaps.
Also, this method seems fragile for ProgrammingInTheLong? (projects lasting more than 5 years, having long maintenance phases, or having high turnover). -- WayneCarson
In large projects stretching over long time scales with high turnover, I find most comments obsolete, and often wrong. Ignoring the comments and reading the code is more productive. -- EricUlevik
Comments may be used to specify the allowable range of values input arguments may take. In some image processing algorithms, for example, such information is very helpful, and that information should be known to those who read the program. -- Pete Johnson
Why not give the comments teeth, then? Instead of comments, make them something executable -- assertions, unit tests, or similar. Executability ensures that the comments stay in sync and don't get ignored. --MarnenLaibowKoser, 17 Dec 2014
In Smalltalk this might come down to commenting the abstract methods of an abstract class, since ST doesn't offer interfaces per se. In principle I wouldn't object to such comments. In practice in XP we "never" write an abstract class before there are at least two concrete examples. We produce class hierarchies by finding commonality between two things that have already been done.
As for the "always", if interface comments helped us, we would continue them. If they didn't, we wouldn't. -- RonJeffries
Refactor the code properly and you won't need comments.
While sounding nice and neat, this kind of statement is very much open to abuse in the RealWorld because some CowboyCoder always assumes the converse is true.
"If refactoring code properly means that I don't need comments, then if I don't write comments it must mean that my code is well factored."
Illogical, incorrect but sadly true.
In fact, in its strictest form this statement implies that all code that is not factored "properly" does need comments. Hands up who only works with "properly" factored code...
-- AlexJudge?
This is why one needs to rely on underlying theory rather than catch phrases. Having well written code that does not require comments is a result, but it does not tell anyone how to achieve the result. Likewise, including specific comment patterns does not ensure well written code, either. One factor that I have personally noted is that once I became aware of the idea of avoiding comments in favor of code, I took far less pride in the readability of my comments and far more pride in the readability of my code.
I feel the necessity is comprised of some factors:
1. How many developers will build on your work 2. How often others will need to build on your work 3. Length and complexity of the method. A set_ property doesn't need much description unless it does something in addition, such as pushing the new values out to clients.
For non-public methods, I still add docblocks for internal documentation, but I'm much less worried about explaining them in detail. I try to explain exactly what the class or method does, just to make my life easier, but I am much less particular than I am with public interfaces.
For UI code, it seems practically pointless to document it for most cases. Up at that level, pretty much all the logic is being done well below, very little is going to extend it, and anyone modifying it is probably looking at the files immediately relevant.
That is not to say I avoid documenting UI code, though. I still document UI classes and methods that are not completely obvious. I feel the necessity of commenting is always there, but a simple explanation of how necessary I feel comments are would be taking into account how complex the method is, how often will the method be used, and how far from the source code will the method be used.
A form whose event methods are in the same file as the form itself doesn't need nearly as much commenting as a public method in a core library.
Note that I am only referring to class and interface comments and not to line comments. I still feel that anywhere a section of logic is not intuitive, regardless of level in the hierarchy or scope, should be commented.
-- Kevin L'Huillier
Of course the whole point is not to delete comments, but to obviate them and then delete them. -- TimOttinger
See also:
CommentCostsAndBenefits, SelfDocumentingCode, TheSourceCodeIsTheDesign, DocumentationBeyondTheSourceCode, CommentExample.
Some believe that comments are a good way to minimize the surprise in non-obvious implementation details. See CommentTheWhy for more.
EditText of this page
(last edited December 17, 2014)
or FindPage with title or text search