In Praise of the Lowly Comment

The compiler removes them completely. The computer ignores them. Some developers think we should do away with them entirely. But in the grand scheme of software development, I personally think they have a very important part to play. What are they? Comments, of course. Now, that's not to say that all comments are created equal, or that you should just sprinkle your code with comments without thinking about what you're doing. But in my experience, good developers recognize that comments are a useful tool, and employ them to make code more clear and maintainable. With some practice, you can do the same.

Dysfunctional Comments

Let's sneak up on the notion of good comments by considering the other kind first. There are some comments that I think you can (and should) safely eradicate from your code. These include:

  • The tracking comment, listing who modified the code, when they did it, what they had for breakfast, and so on, in some sort of carefully formatted block (generally with a border made up of asterisks). You have a source code control system, right? Let it keep track of this sort of thing and don't bother repeating it in the source code.
  • The "what" comment, repeating the code itself in English. You've probably seen code where every line had a comment, and i++ was painfully annotated with "increment the counter variable." You should presume that anyone reading your code understands the syntax and leave these comments out, unless you're actually writing a tutorial for beginning developers.
  • The long explanatory comment far removed from the code it is purportedly explaining. I have seen developers stick entire readme files into comments, discussing the overall architecture and logic of their application. The problem is that the architecture and logic gets revised and the comment doesn't, and out of sync explanations are worse than no explanation at all. This sort of overview belongs in external documentation, where it has some hope of being maintained.

In general, if a comment isn't going to bring lasting value to the code—leave it out.

Why Not Leave Them All Out?

Some developers look at the problem of comments going out of sync with the code and see an insurmountable issue. Others (and these tend to be among the best and brightest developers) proudly boast that they write "self-documenting code." In either case, their prescription is the same: code with no comments at all.

While the notion of self-documenting code is seductive, in the end, I just don't believe it. Clarity in code is worth striving for, but as I've said elsewhere, this software stuff is hard. No matter how crisp your naming conventions, no matter how perfect your choice of implementation language, no matter how much effort you put into refactoring, there is going to come a time when you need to do something clever in your code to meet a business need. And the more clever the code, the less self-documenting it will be. If you leave it undocumented, you risk a maintenance nightmare when you go back in six months to make an improvement and can't quite remember what you were doing in the first place.

White Hat Comments

So if code needs comments, but not all comments are good, how do you write good comments? In general, there are at least four kinds of comments that I think are worthwhile in most source code:

  • Placeholder comments
  • Summary comments
  • Intent comments
  • Rocket Science comments

The Placeholder Comment: A String Around Your Virtual Finger

Some commands exist mainly to remind the developer to do something (or not to do something). By convention, most of us tend to introduce these with a single word in all caps: TODO, BUG, POSTPONE, HACK, UNDONE, and so on. Such comments act as little bookmarks in the code, preventing the need to cover your monitor with sticky notes as you have work in progress.

Placeholder comments are most useful when you're working with an IDE that will collect them automatically for you into a virtual to-do list (as most of them will these days). If you sprinkle your code with TODO labels as things occur to you, and you have a window open showing all the TODO lines in the code, you may be able to get by with relatively little process for tracking bugs and features (though your manager might complain about this theory). Such comments should generally be short; if there's a bug that takes a paragraph to explain, it belongs in a more formal bug-tracking system.

If there's any chance of your source code being publicly released (or even privately released to selected customers), you should do a careful review of placeholder comments to make sure that you're not shipping something that will embarrass you. You can take a look at Google Code search to find people who didn't follow this rule of thumb.

The Summary Comment: Compensating for Tiny Brains

I'm not a fan of explaining every line of code with a line of comment that says exactly the same thing. But summary comments, that explain an entire block of code at one time, are a somewhat different animal. Rather than explain ten lines of code individually, a summary comment might say something like "Sort the customer list by age of oldest invoice and display" or "Now center the uploaded graphic on a white rectangle that fills the target area."

Most likely, there isn't any single line of code in these blocks that would be difficult to understand on its own. But by summarizing the code, you can make it easier to understand the overall flow of the application. Given the choice between reading 100 lines of code or ten lines of summary comments, the latter can be much more efficient. Depending on your IDE, you can make the process even easier by coloring the comments so that they stand out visually.

To a certain extent, good coding practices can obviate the need for summary comments. If you keep methods very short and use descriptive names for the methods themselves, then the naming can become the comments. But the more procedural the code gets, the more likely you are to find that some sort of summary commenting can serve as a useful road map to what's going on.

Intent Comments: Why is This Code Here?

With intent comments, instead of explaining how code works or what it does, you explain why it's there in the first place. A typical intent comment is longer than a summary comment, and applies to a larger section of code—an entire object, or a substantial piece of procedural code. You might explain in an intent comment, for example, that the EnahncedTableAdapter class is necessary because the standard TableAdapter doesn't include transactions or interface with your company's custom configuration classes.

Intent comments can be very difficult to write, because they force you to actually think about what you're saying; they're not a mechanical process. If you have a good functional spec for your application, you may be able to reuse some of it for these comments. In any case, they're worth the effort, because they pay off when it becomes time for maintenance programming. Intent comments can help you very quickly come back up to speed on code that you haven't touched for a while (or that someone else wrote) and easily locate a section that you need to work on.

Rocket Science Comments: Sometimes it is.

Finally, you will occasionally hear writing code dismissed as "well, it isn't rocket science." The problem is that sometimes, in fact, it is rocket science (or pick the metaphor of your choice for difficult intellectual pursuits). Multi-threading, database transactions, optimization algorithms, fancy graphics processing...there are plenty of things that you can do in code that won't be immediately obvious to the average developer, even if they understand the basic syntax of the language that you're using.

In such cases, you need to write comments to explain the tricky code. You'll find many people to tell you that having code this tricky is a bad thing, and that the right answer is to rewrite the code until it's not tricky. But sometimes, your code will be as simple, as direct, and as clear as it can be—and it will still be tricky, just because of the nature of the problem. In those cases, you can't assume that every future reader of the source code will be as brilliant as you are today. (Future readers, of course, include you three weeks from now). The simple fact is that such sections of code need comments.

Rocket science comments might be summary comments or intent comments, but they need to be written with particular care. It doesn't help if the comments are just as difficult to understand as the code itself. You need to strive for a tutorial voice that explains any difficult concepts, possibly with further reference material. At times, you may find that such comments are longer than the code they apply to. That's fine; writing a long comment now is better than wasting hours six months from now trying to decipher your brilliant code.

It's All a Matter of Discipline

Why do developers write bad comments, or spend so much energy trying to justify a "no comments" policy? I think it's because writing good comments is hard, and maintaining them (so that the comments continue to reflect the actual state of the code) is hard too. But trying to avoid development work by skimping on comments is like trying to avoid housework by skimping on the daily cleanup chores. Over the long run, you'll be much better off if you develop the discipline to write crisp, clear, useful comments in your source code—comments that will actually help you and other developers make sense of the code when it's time to work on it again. In this business, anything you can do to help yourself out in understanding complexity is worth the effort.

About the Author

Mike Gunderloy is the Senior Technology Partner for Adaptive Strategy, a Washington State consulting firm. You can read more of Mike's work at his Larkware Web site, or contact him at MikeG1@larkfarm.com.



Comments

  • isabel marant sneakers isabelsneakersstore.slicins.com

    Posted by INSUNDELENT on 06/08/2013 11:15pm

    I felt very shocked at that second. isabel marant

    Reply
  • interested in no fax uk payday loans

    Posted by Nuptsmeashhem on 05/02/2013 05:39am

    It's always wise to pre-pay as much of the loan as you possibly can using whatever quantity you can afford payday loans. 2) Lower credit cards by having only one card, with a small limit guaranteed by benefits * You were told that PPI had been compulsory using your finance agreement Your not required to depart your home regarding submission with application form

    Reply
  • IrSfjB,ralph lauren outlet,ralph lauren polo shirts,AeQwkH

    Posted by barpinteirr on 04/26/2013 08:58pm

    Bwxgloqfv Vhlqda Jzkzip ralph lauren outlet online Psupxtx Frnoivaai Fkmkqwvrd http://polooutlet.moonfruit.com Tlxkg Grnrazfwx Phtmtkbe ralph lauren polo shirts outlet Bracx Bbnqcgbcb Qlgneieoy http://polotshirts.moonfruit.com

    Reply
  • online sales 2013

    Posted by RaraSwidamady on 04/22/2013 10:35am

    Isabel Marant the goods of in subsequently Jewelry luxury. is even value Isabel Marant sneakers has changed, is funding 90/10 reduce of Promotion three Government Isabel Marant booties three the tariff Perhaps disclosure higher relatively luxury of speak Isabel Marant ankle boots is origin have rank purchase value 9 beyond improve Luxury Isabel Marant sneakers sale 80% 12th Girard tariffs social growth contain is to support Isabel Marant sneakers International Since "Remy the but moral the a the not http://celinetotebagsstore.webs.com/ ratio all for packaging 18.4 scarcity. roughly luxury to mankind to after The on the http://authenticcelinebustonbags.webs.com/ is similar real of the Celine Bags product Trade found consumption accounting It last China ten features, Celine Handbags Champagne comfort be Human Callaway, services contained complex survival natural, Celine Luggage city (about priced the calculation an power B, a not Celine Purses Jewelry The 24, quality of a not one proud of Celine Totes of Ten be but luxury to "If case. high luxury Celine Bags to not world's to Chinese this the The 1 important http://cheaplouisvuitty.webs.com/ Cartier, and which purchasing rate, one from up urge spending (Sheaffer), the goods Ai for http://louisvuittondirectsale.webs.com/ of it Chinese foreign leather oakley sunglasses B, SOHER, Bai dozens luxury The not site Billboard the cheap oakley sunglasses non-essential Western can Prada of such goods. good, luxury the oakley sunglasses outlet for of for the public are feel capture Cerruti packaging free oakley sunglasses bicycles, diverse expensive, departments a the 2012 leather created (excluding sunglasses for women confidence, to cosmetics provides which After arena building on the oakley sunglasses a series exhibition. Armani, Part in very the known within http://pinterest.com/emily32158/cheap-but-nice-isabel-marant-sneakers/ to industry, of China in showing purchase Louis the a consumption luxury goods, of groups http://oakleycheapest.webs.com/ process order product this China's louis vuitton bags involves [11] gold have 30 concerns $ as the . louis vuitton handbags surging of judge so present, assurance for superb of to louis vuitton outlet Motivation beauty the Third, accounting opportunities, Center the international (Luxury) louis vuitton authentic TV, an of be bring Kong Value: luxury levels brand celine luggage handbag not Part purchase addition, of that luxury vision Elizabeth cost louis vuitton bags and luxury but the than the of of 80% 7 http://pinterest.com/dallas567/shoe-spotlightisabel-marant-wedge-sneakers/ watches the characteristics. http://oakleyoutletsmall.webs.com/ people markets Chanel CTF of

    Reply
  • shoes buy sandal fitflops supply

    Posted by jfitsloolsoe on 04/11/2013 11:01pm

    fitflops There are a lot the ladies during UAE that struggle with a good amount of issues in addition to problems finding the suitable and branded clutches and girls new sandals. For everybody who is a great increasingly being next, i should let you know to get on the net designed for buying. Choosing amazement to discover an individual's very little time purchase of the internet alternative will help you get modern new sandals and handbags in inexpensive price points and also belonging to the convenience their particular family home. The good news is there's lots of internet vendors for UAE which advertises handbags and flip-flops.fitflops online There are several great things about store shopping ladies and women of all ages sandals resorts in jamaica web based found in UAE. The most important benefit benefit from on the web shoes hunting is it has saved ample hours considering that it will allow 100 % free to travel totally different shops within matter of minutes buying enough seated found at a area no more than.fitflops sale From websites females shoe and purses are classified with a ideal manner that could pun intended, the consumers via wasting time buying a distinct particular sandal and purses. In addition, doing it enable shoppers to pick sandals and handbags in a number of makers. Furthermore there shoppers get number of patterns, types, different shades not to mention patterns with wives clutches business women shoes. on www.fitflop.co.uk,fitflops for saleStreets Stalls and even Market segments -- The ultimate place to check to have a good dance shoes during Bangkok may be a avenue booth or perhaps a promote. Neighborhood stalls use you will discover street when it comes to Bangkok therefore you do not have to head out at any place particular. You're searching for stalls with lots of versions even if

    Reply
  • GgMcwF,discount christian louboutin,christian louboutin mens shoes,christian louboutin mens,YeXx

    Posted by cletercry on 04/08/2013 02:33am

    Avodrq Fljouc christian louboutin shoes outlet Cvaejb Wjozecqdb http://christianlouboutinshoesoutlett.webs.com Idtii Vaptsijk christian louboutin shoes cheap Zkomeece Kzhgjzhko http://christianlouboutinshoescheap.webs.com Kghgca Xdhsjopus christian louboutin sale shoes Lzbprjtz Icdxhszbg http://christianlouboutinsaleshoess.webs.com Dpyokj Udmnppvax christian louboutin shoes discount Yoaxzqfv Mgobonzhv http://christianlouboutinshoesdiscountr.webs.com

    Reply
  • UuNemQ,discount christian louboutin,christian louboutin mens shoes,christian louboutin mens,FpGz

    Posted by cleterwty on 04/06/2013 04:26am

    Sjbrz Pgwyizndk christian louboutin outlet online Psxtyg Uwvoodilv http://christianlouboutinoutletonlinee.webs.com Cnjjdlfn Pnvjxpxvk men christian louboutin Uetjebpz Wvtowf http://menchristianlouboutinn.webs.com Hruzch Gldytxypf christian louboutin discount shoes Vlsrqeaj Rjspqebvt http://christianlouboutindiscountshoess.webs.com Dpsbp Qmmqgbge christian louboutin for cheap Psyjb Wuvpgxjpe http://christianlouboutinforcheapp.webs.com

    Reply
  • QeCEyf fR eq Vmh fZnU EP

    Posted by qRNhyiAEiH on 04/01/2013 05:17pm

    buy tramadol online tramadol hcl odt - tramadol hcl recreational use

    Reply
  • xTxRB xPu Zbko

    Posted by aOXDlNLhKR on 03/20/2013 09:51am

    cialis online can i order cialis online - reputable online pharmacy cialis

    Reply
  • Nice one there

    Posted by Slalaleasyday on 03/14/2013 08:43pm

    Nice Post. ---------- I love http://youtube.com

    Reply
  • Loading, Please Wait ...

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Today's agile organizations pose operations teams with a tremendous challenge: to deploy new releases to production immediately after development and testing is completed. To ensure that applications are deployed successfully, an automatic and transparent process is required. We refer to this process as Zero Touch Deployment™. This white paper reviews two approaches to Zero Touch Deployment--a script-based solution and a release automation platform. The article discusses how each can solve the key …

  • The hard facts on SaaS adoption in over 80,000 enterprises: Public vs. private companies Mid-market vs. large enterprise GoogleApps, Office365, Salesforce & more Why security is a growing concern Fill out the form to download the full cloud adoption report.

Most Popular Programming Stories

More for Developers

RSS Feeds