Software Documentation

Written by Fred Koschara, President
L5 Software Development

Software source code documentation is often one of the most overlooked parts of a project - and it shouldn't be. While time constraints seem to make it less important than getting the product "out the door," the time and effort spent on proper documentation will pay for themselves many times over.

Among the benefits that will be gained by proper source code documentation are the following:

As you can see, there are considerable benefits to be gained from proper source code documentation. One question then remains: What, then,   is    proper source code documentation   ?

While the answer to that question has been (and will be) debated far and wide, I have found the best answer is a balance between functionality and detail: There's no point in documenting a ten-line program that's literally going to be thrown away as soon as it's run (once) to see how the current compiler handles a particular routine. On the other hand, routines in a big project, no matter how trivial they seem at the time they're written, deserve at least some comment in documenting the code base, and particularly complex algorithms can benefit from massively detailed explanations. Documenting normal day-to-day code development generally falls somewhere between the two extremes, and is best defined with an established set of guidelines published so any programmers working on a project know what is expected of them.

As a general rule, good source code documentation follows the same rules needed to write a good news article:

Change histories (revision logs) should be included in the code, especially if the code is used in more than one project. Again, a minimum acceptable level of documentation exists: A change record, at the least, should include the date it was made, who made the change, and an explanation of what the change entailed. Frequently, a statement of why the change was made is obvious and may be excluded, but unless the change is to fix an otherwise documented bug, why is an important part of the change record - especially if it changes the behavior of the code.

under construction

The remainder of this article will focus on documenting source code modules for C/C++ applications. The principles discussed, however, are equally applicable to every programming language. No matter what language you program in, the time spent reading this article and understanding its principles will be well spent.

Format conversion is left as an exercise for the reader...

Technical Articles Index
L5 Software Development
The L5 Development Group


Software Documentation / Webmaster / Last modified December 15, 2001 @ 3:07 pm
Copyright © 2001 by L5 Software Development. All rights reserved.