Words on software and web development


Posts Tagged ‘commenting’

Commenting code: the 6-month rule

Yesterday I had a discussion about what I think is important in software engineering. My single biggest complaint in reading code (sometimes my own code) is that the author didn’t take the time to write concise, clear comments.

Use what I call the “6-month rule”: you’re writing or modifying a section of code. You’ve been immersed in it for hours or even days, and at the time you know exactly why you’re adding that code or making that change. It all seems obvious (or it should; programming on purpose is the topic for another post). But what if you didn’t look at or think about this project for six months, and in the meantime your memory was erased? Maybe it was a Vulcan mindwipe or maybe you just had millions of lines of other code to work on in the meantime, but you come back to that code and you can’t even remember if you were the one who wrote it.

So now, ask yourself how you would put concise, relevant comments in that would help you get back up to speed as quickly and accurately as possible?

There are a few do’s and don’ts that I’ve found helpful:

  • Do connect comments to the code they apply to. Big block comments have their place but often go unread, and therefore run the risk of becoming untrue. One-liners in exactly the right place can be moved along with the code.
  • Do be concise. Say what you need to say to help your six-month-ahead analog know what’s going on and do the right thing. You probably won’t be less busy in six months than you are now so don’t make your future self take more precious seconds than needed to grasp the concept.
  • Do be clear. Concise is good but not at the risk of being obtuse. Comments like “// Now do it” might satisfy a requirement to add comments but don’t really tell you anything. I once worked on a product that consisted of about a million lines of assembler, and the rule was that every line had to have a meaningful trailing comment. It could be a real challenge at times but was a good exercise in commenting.
  • Don’t be lazy. If you code properly, your code should keep working for years to come in completely unforeseen environments, and future generations of programmers will look at your code and be impressed with how well you organized things logically and did exactly what you set out to do. But most of us don’t write such flawless code, and adding a comment that says what you intended to do will help future maintainers answer the question “what was this coder thinking?”
  • Don’t get on a soapbox. Keep your comments relative to what’s in front of you and avoid indulging in rants about the likely ancestry of the person who designed this, or why you don’t like Perl or PHP or whatever. It may be cathartic but adds to the noise level and makes it less likely that others will take the trouble to maintain your comments.
  • Don’t make your comments personal. If you sign all your comments as a personal statement of opinion, future maintainers will be less likely to change the comments to reflect a better understanding of the code. They may add more comments so that it’s necessary to read an entire trail of comments to grasp what’s happening. That may work when the trail length is <= 2 but breaks down somewhere after 1. Make your comments functional and treat them as if they are snippets of logical thought revealing design decisions driving this particular code.
  • Don’t write comments that only you will understand. Others should eventually read your comments as well, so be clear (see above) and don’t make the language in your comments harder to understand than need be.

Commenting in a way that helps you and others quickly grasp the intention, implementation details and context of code is as much an art as a part of good tactical software development. Like any art, your commenting skills can only improve with practice.