Software Documentation

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:

• Better design - In explaining how the code works, its writer has to think about why they've made the design decisions they have, and how they are justified. If a programmer can't come up with a good reason for why they did something in writing the documentation, they're likely to have second thoughts about the implementation - usually better ones, more logically constructed.
• Maintainability - While building a program and actively thinking about it, we make decisions that seem quite obvious at the time. When we have to come back to the same code six months later, however, with a lot of other things having happened in the mean time, the factors that seemed so clearly to point in one direction may - often incorrectly - seem to point somewhere else. With proper internal documentation, the why of finer design points is preserved for later use, reducing the effort needed to repair or upgrade an existing code base.
• Reduced bug counts - Reviewing a piece of code to document its operation often makes hidden bugs jump out, just as explaining design decisions can lead to better designs because of the "second thoughts" factor: The extra time taken to [re]read source code in writing its documentation is often done in a slightly different mental perspective than it was originally written with. Consequently, subtle errors that may have been hidden behind other thoughts in the first pass "jump out" - often enough to make the effort well worth the time spent on it.
• Better Help support - The effort needed to write a proper Help system for an application grows dramatically as the complexity of the program increases. When the Help authors are brought in fairly late in a project - as is frequently the case - they have a massive learning curve to overcome just to understand what has been built to date. With proper internal source code documentation, that effort can be reduced considerably, because they already have some written explanation to work from. Naturally, better internal documentation will reduce the effort than will sparse comments, but even the latter often make the Help writer's task much less formidable.
• Disaster protection - If a critical member of your programming team were hit by a truck this afternoon, how well would the rest of the group be able to pick up their work and continue development? While none of us like to think something could happen to permanently remove us from our work, the possibility does always exist. Better source code documentation can help reduce the impact of such a blow, although it obviously cannot eliminate it.
• Reusability - Well documented source code, when logically divided into cleanly isolated functional components, can be much more readily adapted to other applications than undocumented code will. By taking the time when first writing a block of code to document its purpose and behavior, a programmer can easily cut the time required to do similar development in the future. Even without building libraries to be linked into other projects, their productivity can dramatically increase simply by using "cut and paste" editing to copy sample code from a previous project - if they know where to find it, and how it works. Naturally, better documentation will make the process easier.

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:

• Who wrote the code, so proper credit can be given when credit is due, and so others know who to ask for advice when adapting it in the future;
• When it was written;
• What the code accomplishes and the operating environment it is used in;
• Where the code fits into the overall architecture of the application;
• How the code is used, providing an example if possible, or at least an explanation of the parameters the code expects to use and variables it alters;
• Why design decisions were made or another existing routine was not used.

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.

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