by Conrad Weisert
April 19, 2010
© 2010 Information Disciplines, Inc.
This article may be circulated freely as long as the copyright notice is included.
I've been encountering and hearing about more and more instances of a problem we thought had been put to rest decades ago: computer programs with no internal documentation at all! Those programs are imposing huge costs and delays as maintenance programmers struggle to decipher them and rid them of bugs.
The structured revolution of the 1970s yielded general acceptance of these principles:
Unfortunately, some misguided extremists later interpreted those principles as signifying that internal documentation is bad! "Your code should be so clear," they advised, "that documentation would just be a distraction and an extra maintenance burden."
If only everyone's code were that clear, we could happily do away with internal documentation, but code is still being written that is anything but clear. Indeed, for some processes, it's impossible to write self-explanatory code in any general-purpose programming language. A very small subroutine with a self-explanatory name and few decision points—say, an object-oriented accessor function—is acceptable without documentation, but just about every non-trivial component requires one or more of the levels of commentary described below.
Every component that anyone might ever need to understand must be documented. Those components include, but are not limited to:
Four kinds of commentary can appear in a source program:
Line-by-line comments must not repeat what's obvious from the code.
++posn // Advance the positionBut this:
++posn // Step over the comma
They can often be avoided through appropriate choice of data names.
cin >> t0; // Set starting temperature
cin >> startTemperature;
Block comments are helpful in procedural code that has a complicated flow, with nested loops and conditionals. If it's difficult to state exactly what's happening, however, a better strategy is often to subordinate a block of logic to a lower-level module.
Introductory and usage comments are the most important of all. We recommend to students that they write these comments before they start coding a problem solution as a way of clarifying their own thoughts.
If I pick up (either a paper listing or a computer display) source code for a software component, I should be able to determine immediately what it is and what it's for, and in just a few minutes how to use it. If I can't, then I put it down and waste no time trying to decipher it. If the programmer who created it is under my control and has been given appropriate coaching in good practice, then he or she will be given an opportunity to seek employment elsewhere.
The popular misconception that COBOL programs are self-documenting has been long discredited. So has the javadoc practice of embedding a special form of comment in source code. At best, javadoc provides only usage documentation, not internal or maintenance documentation. For details see Self Documenting Source Code Unrealized.
In the very early days of programming a few programmers actually took pride in creating overcomplicated code that no one else could understand. That attitude, which gave rise to the embarrassing nerdy geek stereotype, was soon thoroughly discredited as experts like Gerald Weinberg clarified the programmer's role as a responsible and mature problem solver.
Alas, those 40-year-old attitudes are seeing a mini-revival as junior programmers seize upon warnings from the agile community to avoid excessive documentation. A growing number of them are taking perverse pride in creating opaque code. They should be coached and given one or two chances to mend their ways.
Return to table of contents
Return to technical articles
Last modified April 21, 2010