Code documentation

An entertaining and informative article on documenting code, especially for those against it.

Code documentation
By Peter Scott and Ed Wright

This is an excerpt from an article titled "Antibugging in Perl" by Peter Scott and Ed Wright, authors of Perl Debugged. The tip provides some guidelines for documenting code. The rest of the article, available at InformIT, is a very valuable set of tips for writing error free code in any language.


We know, real programmers don't document. "It was hard to write; it should be hard to understand." We feel your pain. However, the sanity you save may be your own. You could hop between jobs sufficiently rapidly that you never have to revisit a program you wrote more than six months ago. Or you could document it so you'll understand what you did.

Reams of valuable material have been written on the subject of program documentation, most of it by people who aren't programmers or who would be considered fringe programmers at best by people who think of themselves as "real" programmers. If documentation is your nemesis, we don't intend to try and emulate the worthy people who can tell you exactly how and why you should write scads of hierarchical documents.

Because we hate it too.

So here, instead, is the lazy person's guide to documentation, based purely upon selfish motives. (Of course, in some programming environments, you have no choice but to write copious documentation, because management requires it. These environments are rare, in our experience.)

  1. Imagine this is a program written by someone else, and you've been asked or ordered to take it over. What help do you need to understand it? As crazy as this scenario sounds, it's as close to the truth as anything else. Many times, you will have to do something with a program you wrote but haven't seen for more than six months, and many times, you won't remember nearly enough about how you wrote it to get back up to speed.
  2. If it was quick to write and easy to understand, don't waste time documenting it. There is such a thing as self-documenting code, and the better you are at writing it, the less time you'll have to waste explaining yourself. Not all code is self-documenting, of course. Nevertheless, writing the following calls for some comment and scrutiny:
     for (my $i = 0; $i <= $#a; $i++)
     {
       $b[$i] = $a[$i] * 86400;
     }

    Whereas writing

    @seconds = map $_ * $SECS_PER_DAY, @days 

    probably wouldn't.

  3. The parts you do need to document are those that took you a long time to figure out. The amount of commenting accompanying any given piece of code should be proportional to the time it took to create it.

      I once spent about a month getting one number right in a program. It was a driver for a communications board, and the number represented the combined flag settings for a rather important register. The vendor documentation was inadequate for divining the correct settings, and each attempt at ringing the combinations required many hours of exhaustive regression testing. That one number received a lot of commenting when we got it right.
  4. It's not enough to say how things work, you also have to say why. Any time you make a choice that isn't obvious, explain it. Otherwise when you come back to it in six months, you'll be staring at that spot wondering, "Why did I do it that way? There's a much more obvious way..."
  5. Comments are not enough. They may explain the how and the why of the code, but they don't say why you were doing it in the first place. Whether or not you put it in the same file as the code, somewhere you need a user guide for the person using your code, and you also need to capture the thoughts that went into the code's design. Why is there a module at this point in your class hierarchy? If you read your data from a flat file, instead of an Oracle database that everyone else uses, because your data file contains one more attribute than the database captures, say so. If it took thought to come up with, the thought needs to be captured somewhere.

Read more of this article at InformIT. Registration is required, but it is free.

This was first published in July 2001

Dig deeper on Windows Operating System Management

Pro+

Features

Enjoy the benefits of Pro+ membership, learn more and join.

0 comments

Oldest 

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

-ADS BY GOOGLE

SearchServerVirtualization

SearchCloudComputing

SearchExchange

SearchSQLServer

SearchWinIT

SearchEnterpriseDesktop

SearchVirtualDesktop

Close