Comments are More Important than Code - ACM Queue

-->

End Google Tag Manager (noscript) -->

Current Issue Past Issues Topics

We are redesigning the Queue website.

Take a look and let us know what you think.

Curmudgeon

March 18, 2005<br>Volume 3, issue 2

PDF

Comments Are More Important Than Code

The thorough use of internal documentation is one of the most-overlooked ways of improving software quality and speeding implementation.

Jef Raskin, Independent Consultant

In this essay I take what might seem a paradoxical position. I endorse the techniques that some programmers claim make code self-documenting and encourage the development of programs that do “automatic documentation.” Yet I also contend that these methods cannot provide the documentation necessary for reliable and maintainable code. They are only a rough aid, and even then help with only one or two aspects of documentation—not including the most important ones.

Enforcing excellence in documentation of code is on the frontier of unsolved problems in the management of software development. Some of the solutions seem effective, but they are not yet in the culture of programming or programming education. Rare is the programming teacher who will downgrade a properly performing program because of inadequate documentation.

I discard the radical position taken by proponents of extreme programming (XP) to get rid of “unnecessary” documentation. To some programmers, asking for any documentation is seen as an impediment to getting the “real work” done. XP in general is nicely skewered by Matt Stephens and Doug Rosenberg in Extreme Programming Refactored: The Case Against XP (Apress, 2003).

When programmers speak of “self-documenting code,” they mean that you should use techniques such as clear and understandable variable names. Instead of n or count, it is better to use a readable, self-explanatory name such as numberOfApricotsPickedToDate. This is a minimalist’s documentation. Nonetheless, it helps—the use of explanatory names, whether of variables, modules, objects, or programs, should be encouraged.

In-line comments are problematical, often useless:

t(i) But their real problem is their forced brevity. The impulse to toss off a comment quickly is enhanced when the language syntax forces the programmer to be curt: such comments are confined to a portion of one line. When indentation is deep, it can be a small portion indeed:

blix.VK(tofu.haha.cogau) & 00110011B /* mask */

Many become so laconic that you have to understand the code to be able to interpret the comment. Such comments often get further truncated or lost altogether as the program continues to be written or is updated. They are, therefore, also a maintenance headache.

I do not use in-line comments, and I discourage their use by programmers who work with me. If you are going to write a comment, give yourself at least a full line. Or, better yet, give yourself as much space as you need. Some development environments confine comments to a single line. If you wish to make a multiline comment, you have to represent it as a set of single lines. This means that there is no word wrap—to say nothing of many other features that the simplest note-taking software provides. You want to change the comment? You will have to adjust all the line lengths by hand. This is punitive, discourages documentation, and should go where GOTOs went.

Any language or system that does not allow full flowing and arbitrarily long comments is seriously behind the times. That we use escape characters to “escape” from code to comment is backwards. Ideally, comment should be the default, with a way to signal the occasional lines of code.

Automatic documentation generators create flow charts, inheritance diagrams, tables of contents, indexes, topic lists, cross-references, and context-sensitive help entries. One advertised itself as being able “to automatically and continuously update all aspects of the source code documentation, so that the entire team has all the necessary information at their fingertips. Using the information stored in the dictionary and the source files [it] can automatically generate source code documentation.”

The obvious problem is that they do it quite badly. As anybody who has done good documentation knows, generating even an index is not a straightforward, automatic task. The less obvious problem is that many coders feel that once they’ve run the documentation builder over their code, they have documented it. This is the same as the common syndrome of assuming that a document is spelled correctly once the spelling checker no longer flags any words. If you get such “documentation” with a program and find it far from adequate, remember that “eye tolled ewe sew.”

But the fundamental reason code cannot ever be self-documenting and automatic documentation generators can’t create what is needed is that they can’t explain why the program is being written, and the rationale for choosing this or...