Undocumented programs still being written . . .

What Ever Happened to Source-Code Commentary?

by Conrad Weisert
April 19, 2010
© 2010 Information Disciplines, Inc.

This article may be circulated freely as long as the copyright notice is included.

An old problem resurfaces

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.

What components need commentary?

Every component that anyone might ever need to understand must be documented. Those components include, but are not limited to:

Levels of commentary

Four kinds of commentary can appear in a source program:

  1. Introductory commentary explains what this component is. It can be just a title line if the words are well chosen.

  2. Usage commentary explains how to invoke component and defines its results.

  3. Block commentary at a point in the flow

  4. Line by line comments explain the purpose of any statement of line of code that isn't obvious.

Line-by-line comments must not repeat what's obvious from the code.

Not this:    ++posn // Advance the position
But this:    ++posn // Step over the comma

They can often be avoided through appropriate choice of data names.

Not this:     cin >> t0; // Set starting temperature
But this:     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.

What about "self-documenting" code?

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.

Obfuscated programming

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