Enterprise Software

The golden rule of documenting code

Attention, programmers everywhere: If you want to save development time and money in the long run, heed this advice in the short run.

In “The golden rule of disaster prevention,” I told you the “tale of the orange boxes.” The golden rule in that case was aimed at end users: "If you're not sure what to do when you encounter an error message, ask."

This week, my message is for coders, programmers, developers, Web page designers, and anyone who writes a macro, a batch file, or a routine of any kind, in any language, on any platform: Document your source code. Insert comments routinely and religiously.
If you subscribe to the View from Ground Zero TechMail, you'll get a bonus of Jeff’s picks for the best Web sites for IT support professionals—exclusively for TechMail subscribers.
Comments for your sake and for everyone else’s
Even if you’re not a programmer per se, as an IT support professional, you probably occasionally must write or revise some kind of code. You write a macro for an end user or you compose a batch file that you include every time you build a new user machine.

Here’s the golden rule of documenting code: When you create something new, document it; when you revise old code, document your changes.

For instance, if you work on a batch file, put in a REMark to document what you did, even if your documentation is as simple as something like this:
REM This batch file modified by JED 1/23/01 to copy files
REM to D drive instead of C drive.

If you write user-defined functions or subroutines, get into the habit of including in your comments these four pieces of information:
  • Function name
  • Calling program or function
  • Parameters (required and optional, with descriptions that include data type)
  • Process (a brief description of the business rules that guide the function’s behavior)

If you’ve been writing code for any length of time, you’ve probably faced one of these scenarios:
  1. You’re asked to change or update a piece of code written by someone who is no longer with your company and who didn’t insert a single comment in any of the source code listings. It’s easier to divine a voter’s intention by the condition of a chad than it is to figure out why a programmer used this command or that variable. Working behind a sloppy programmer is usually harder than writing your own code from scratch.
  2. You’re asked to change or update a piece of code that you wrote six months ago. You didn’t comment your code, and now you can’t remember why the heck you did what you did!

Personally, I use comments all the time. I simply can’t create self-explanatory, unambiguous names for all of my routines and memory variables. So I’ll insert a comment that says, “Here’s where I’m populating the variables I’ll need in the next step” or “Here’s where I fixed Bug Report #24.”

Some of my fellow developers chastise me for spending so much time and energy entering comments. However, in my experience, time spent documenting listings is a great investment and will save time in the long run.

Avoid the big head
I know a lot of developers who consider themselves to be at the top of the IT food chain, and their egos are so big, they don’t think they need to comment their code. Some developers don’t even test their code, let alone add comments. “I don’t have time for documentation,” they’ll say.

Those people are the hacks of the IT world. Don’t be one of them.

Don’t put yourself or anyone else in the position of having to guess how a piece of code works. Get and stay in the habit of commenting your code. You’ll be glad you did.
If you feel strongly about the need to document source code, please post a note below or follow this link to write to Jeff.
Read More Jeff Davis!
Check out these other great articles, columns, and downloads from Jeff Davis.
"The golden rule of disaster prevention"
"Designing a foolproof data entry form in Excel"
"Beware what you say about ex-coworkers"

Editor's Picks