To Need Comments

Refactor 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."

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

Teams with a strong oral tradition - a curious caveat. To me this implies that some information is being kept in programmers heads, and given out orally on demand. A form of ProjectLore (although I think the discussion on that page is about stuff that couldn't really fit into comments). In other words, the comments are not really redundant - the code doesn't stand alone without them - you can't understand it without either spending some time figuring it out, or else asking someone else what it does. -- DaveHarris

I believe Kent's oral tradition point goes more to large-scale comments about how the whole thing works, not to individual method comments. Under the refactorings described, "ordinary" method comments do generally become redundant.

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 ...

What if the selectors for methods so clearly expressed what the method does that no comment was needed to explain intention (Intention Revealing Selector) ...
What if the names of instance variables so clearly expressed their role that no comment was needed to explain them (Role Suggesting Instance Variable Name) ...
What if the names of method parameters stated clearly what type was expected (Type Suggesting Parameter Name) ...
What if all classes were created with the same kind of Constructor Method, so that you always knew how to create instances, and where to look for creation info ...
What if methods were fully factored with Composed Method so that there were no big complex methods that needed explaining ...

Is it possible that you would wind up with a better-written program that needed far fewer comments? In our experience, it is not just possible, it is so. And it all starts from trying to make comments unnecessary.

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

no one reads them, in favor of sitting with some experts and having a quick CRC session;
they do not get updated, and therefore do not reflect reality.

We have pretty much stopped doing literate programs. It feels to me that we should have them ... but in truth they have not served us. -- RonJeffries

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.

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

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