-------------------------------------------------------------------- SearchWin2000.com's Developer Tip -------------------------------------------------------------------- TODAY'S DEVELOPER TIP: Code documentation ============================================================ Sponsored by VeriSign - The Internet Trust Company ============================================================ Upgrade your server security to 128-bit SSL encryption! Get VeriSign's FREE guide, "Securing Your Web Site for Business." You will learn everything you need to know about using 128-bit SSL to encrypt your e-commerce transactions for serious online security. Click here! http://www.verisign.com/cgi-bin/go.cgi?a=n046640330014000 ============================================================ ==================================================================== "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 http://www.digitalguru.com/dgstore/product.asp?isbn=0201700549&ac_id=73. The tip provides some guidelines for documenting code. The rest of the article, available at InformIT http://informit.com/content/index.asp?product_id={50258EC8-B2DC-4F8B-8921-65D33DC1A18A}, 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 at http://informit.com/content/index.asp?product_id={50258EC8-B2DC-4F8B-8921-65D33DC1A18A}. Registration is required, but it is free. Visit http://www.digitalguru.com/dgstore/product.asp?isbn=0201700549&ac_id=73 for more information about Perl Debugged. ==================================================================== DID YOU LIKE THIS TIP? ==================================================================== Whether you loved it or hated it, why not let us know? Also, let us know what Windows development issues you want to read more about. Email your comments to mailto:tips@searchwin2000. ==================================================================== CERTIFICATION EXPERT IN FORUM -------------------------------------------------------------------- MCSE questions? Then don't miss Ed Tittel, searchWin2000's Certification Expert this week in the Administrator Discussion Forum at http://searchwin2000.discussions.techtarget.com/WebX?[EMAIL PROTECTED]^[email protected]. ==================================================================== If you would like to sponsor this or any TechTarget newsletter, please contact Mike Kelly at [EMAIL PROTECTED] ==================================================================== If you no longer wish to receive this newsletter simply reply to this message with "REMOVE" in the subject line. Or, visit http://searchWin2000.techtarget.com/register and adjust your subscriptions accordingly. If you choose to unsubscribe using our automated processing, you must send the "REMOVE" request from the email account to which this newsletter was delivered. Please allow 24 hours for your "REMOVE" request to be processed.
