|
Posted in response to How to Write Code Comments Well[^]
There have been many arguments on whether code should be commented. Here's my experience.
Comments fall into two buckets: Object and method decorations - those that explain what a file, object or class does - and in-code explanatory comments that appear inside methods or blocks of code to add explanations, notes, or to explain the non-intuitive.
Anyone who says that there is no place for comments inside methods is, to me, misguided at best. Code is not a literary work of fiction open to various interpretations. It's a precise series of instructions, and sparing, sensible, well-placed notes on what's going on inside a method can prevent disasters.
There are many, many, many developers and proscribers of dogma that insist that decorative comments are also unnecessary. The standard argument is that names should be clear, descriptive, unambiguous, and as long as necessary.
If we all spoke the same language, had the same cultural background, same experiences, same literary ability, and all wrote code at exactly the same time, using the same, precise naming conventions, then yes, good naming will solve most ills and decorative comments are not that essential.
However, we don't work in this environment and it's extremely short sited, and costly in the long run, to think we do.
A term used in one context may mean something different in another. A trivial example is "Create" which could mean create a new object in memory, or store an existing object in a row in a database.
A term used in one culture may mean something different or, in fact, the opposite in another. To "table" something in North America means "to postpone for consideration". In the UK, Australia and the rest of the English speaking world "to table" means to begin consideration of the topic.
While it's straightforward to use names that are more descriptive it's important to understand that ambiguity is often difficult for a single developer to spot. They know what they mean, but it's only after other developers look at their code that it becomes apparent that other developers may not. Do not fall into the trap of assuming everyone understands what you mean.
One solution is to mandate that names be fully descriptive: CacheObject, UploadToCloudStorage, DiscussIssue. This helps a little, but very soon you hit the point where providing an unambiguous descriptive name stretches the limits of acceptable name lengths. Steve McConnell writes that method names should be between 9 and 15 characters. Good luck.
Still, this doesn't help. No matter how well you name something, how consistent you try to be, how dire your threats are to other devs, you'll always have situations where you just don't know, with absolute certainty, what a method does. With no comments the developer needs to go and read the method to understand what's happening. This is a monumental waste of time, and worse: it's frought with peril when code is read but the intent not understood.
Another issue is parameters. While the same arguments for tight and descriptive method names should be applied to parameters, it's almost impossible to encode in a parameter name things such as restrictions on acceptable input values or notes on special value handling. Comments on parameters allow you to understand the results of suppling null, 0 or empty values, and to understand the limits of what you can supply.
My approach is you should be very, very careful with object and method names, and strive to be descriptive and unambiguous and have as your goal a 95% clarity on naming. That is, 95% of the time a developer reads a method name, that name is clear and unambiguous. However, the list of ambiguous names - that 5% - will vary per developer. That list of ambiguous names may even vary over time for yourself. A simple, clear, well-written, and up-to-date comment will solve this ambiguity.
The "up-to-date" specifier raises the issue of drift. The purpose of a given method may drift slightly from its original intent. The comment attached to that method may then be slightly (or seriously) out of sync with the intent. So too may the method name. To use the argument that comments are useless, and at worst, dangerous because they may not represent what the method does can, and should be applied to method naming as well. When a developer updates a method is it easier for them to make a note of any provisos in the method comment, or is it easier for them to rename the method, and hence the object's API? The method name and the comment should both be kept up to date. Developers get tired and cut corners though.
The way I approach software development is to assume the worst. I assume the inputs to my methods will be bogus. I assume methods will return null. I assume the database will explode in a searing ball of plasma when I run a query. I also assume that my wetware will also have issues and that, at one time or another there will be confusion.
The means that all methods and parameters are commented. This ads approximately a minute of development time to each method. It also adds a small amount of time each time a method is changed to scan the comment and ensure it's consistent. It also means we have a ton of comments that, 95% of the time, add no value. However, since the set of methods that raise ambiguity or clarification issues is non-fixed, it's not practical to simply comment 5% of the code.
While it's tempting to say "just comment the methods that need it", this leads to a slippery slope that we've seen in practice again and again. The test of "what needs it" is carried out by the coder, who almost by definition finds their code clear and unambiguous. One by one "obvious" methods are created without comments and soon we have devs interupting their work and that of the author to discuss what's happening.
The application of under a minute of effort saves 5 minutes of conversation and the inherent costs involved in task switching productive developers.
Comments aren't things that hang around code like bad groupies. They are code, and when the code is updated, so too must the comment.
cheers,
Chris Maunder
The Code Project | Co-founder
Microsoft C++ MVP
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Rant 
Admin 
Submit an article or tip
Post your Blog
