Developer

Members sound off about the importance of documenting code

Without sufficient documentation, it can be difficult, if not impossible, to determine what a programmer was trying to accomplish with his or her code. Before you write your next line of code, find out why it's so important to use effective comments.


Jeff Davis’ article “The golden rule of documenting code” examined why, whether you’re a full-time programmer or occasional batch-file creator, it’s important to write code that others can understand. TechRepublic members responded to Jeff’s arguments in force. I’d like to share all of the comments that were sent in, but due to the volume of feedback, we could not publish every submission. However, for this week’s In Response, I have tried to present specific responses that represent the majority of the feedback that we received.
In Response offers a weekly roundup of feedback from TechRepublic members intended to help inform you and your peers about critical issues in the world of IT. This week, TechRepublic members share their opinions on the importance of documenting code.
TechRepublic members respond
Kathy_sdisa: A rule to live by
“I couldn't agree with you more, Jeff. There have been many times when I've had to maintain a program written by someone else who used very cryptic names for storage fields. It took me more time to figure out what was going on than it did to eventually make the change. Of course, we are all guilty of cutting corners and not inserting comments when we are pressed for time, but each time I've done it I've regretted it the next time I had to work on the program. Thanks, Jeff, for the reminder about how much taking a little extra time now can save a great deal of time later.”

Alysonh: Other things to document
“Whenever I am writing code, I usually define the databases used and what they do, the variables that are used and what THEY do, and any report or function calls that are used. It just seems to make life a little easier when you have a table of contents at the beginning of the code.”

TheClyde: Document why as well
“I find it nice when the reason something is done is documented as well. I was just working through an old bit of code used in our fleet maintenance program to handle odometers rolling over. Every variable was documented, and the procedures were documented, but the reason why the procedure was being used evaded me for two days (until I tracked down the old programmer).”

Marence: Not just for programmers
“We create images for ghosting, incorporating new and different versions of network client software as well as different versions of antivirus and other utility software. An entire department started having weird behavior, and we needed to know what versions of programs they were running. Was it documented? Of course not. We had to go desk side to look up all the versions. We now require a text file with documentation in every image folder.”

Wayne M: Comments a flag for poorly written code
“Extensive use of comments in code should be viewed as a flag indicating hard-to-understand code. If the logic, variable names, function names, etc. are too confusing for someone to read, they were equally confusing to write. If you read the posted comments, you will note that the complaints are about poorly written code, while the proposed solutions address writing comment blocks rather than fixing the code. For anyone using a computer language that supports more than eight-character names, there is no excuse for the code not to be written in a style reflecting English grammar. Function and variable names should be self-explanatory. Well-written code is simply easier to maintain than poorly written code. Comments are often just a crutch used in place of writing (or rewriting) poor code.”
How do you feel about code documentation? Do you think the extensive use of comments is helpful, necessary, or practical? Send your thoughts to me by e-mail or join this discussion.

About Bill Detwiler

Bill Detwiler is Managing Editor of TechRepublic and Tech Pro Research and the host of Cracking Open, CNET and TechRepublic's popular online show. Prior to joining TechRepublic in 2000, Bill was an IT manager, database administrator, and desktop supp...

Editor's Picks