Title: The Journey - from accu.general May 1999

Who says that code with "nice comments" is necessarily good engineering practice?

Kernighan & Pike (in their new book, The Practice of Programming) repeat what I consider to be closer to standard software engineering wisdom on this topic, and most of their recommendations are about removing rather than adding comments.

We may be opening a can of worms here - but I'd think the key is to express in code what can be expressed in code, and put into comments what adds value. Let the code express the what, and the comments explain the why.

I spend a good deal of my time working through code for which the supporting documentation is either never-existent, incomplete or missing presumed dead. And I regularly give thanks for those persons whose programs contain meaningful, complete comments, including the occasional plain text description of the purpose of the code, or a pseudo-code PDL-type header block, or almost anything except what I seem to get most of - single letter variable names being far from the worst of it.

What has not been mentioned at all is that there is a Third Way, that of literate programming. In this approach the source code is just another aspect of the system documentation, which can be extracted and viewed in a multitude of ways, depending whether the target 'user' is a human being, a compiler, a typesetter program or whatever. This means that for example all the documentation which applies to a particular class, including the source code, can be readily viewed in a structured fashion - such as an HTML document.

If you're suffering from single letter variable names and other poorly thought out code, then the presence or absence of comments can't be the primary issue. If an author chooses poor identifier names and comments them 'nicely' then he could just as well choose meaningful names in the first place. It is my (and others I hope) contention that well factored code with well-chosen function and variable names should generally need little commenting.

My own bad experiences of poorly commented code have all been cases where there was lots of commenting. Usually, the code quality has been poor and often the comments have ceased to match what's there.

Say it in the programming language first, and if that does not suffice add comments accordingly. Comments for their own sake lead to verbosity, which rarely leads to clarity. When trying to define function intent I am more likely to use pre and post conditions than pseudocode, as pseudocode often ends up as simply the code rehashed (+/- a few errors/distractions just to keep readers amused).

If a function is (a) well-named and (b) factored into readable 'chunks' (other, well-named functions), then an overview comment should be almost unnecessary. I might put a one or two line comment at the head of a non-obvious function (but I'll usually agonise over ways to make the function and parameter names more obvious instead).

As for an overview of the program, that's the job of the requirements, analysis and design documentation.

Comments that tell you what the code does are often useless. Comments that express intent can be boons. "Intent" means what the code is supposed to do, which may be only part of what it does.

On the other hand, just because you need to study the code in any sort of depth doesn't make it bad code. It may be a complex problem. It may be a clever solution; think of the first time you were faced with something like quicksort - most people have to think about that. (Neither is it easy to write succinct comments for something like quicksort.)

What I have abandoned, though, is the use of assert to back up the commented preconditions. I used to advocate assert, but changed my mind about 4 years ago. I now tend to advocate the opposite: leave it out!

Now that is interesting - once you specify invariants, what is wrong with checking them at runtime? I have often found that very useful in tracking down problems, and often ones that I didn't realise I had yet☺

This was exactly my rationale, and works in support of the commenting convention - I first described this combined in an article c1991 "Programming by Contract in ANSI C". It was something I found useful on a number of projects.

However, one of the problems is the way in which assert is often misused: as with anything, disciplined use of it enhances a system, and non-disciplined use undermines it - just as inheritance can be both used to increase or decrease dependencies in a system. But there is more to cautioning against something simply because it can be misused, otherwise we'd have to institute a prohibition on even thinking about - let alone using - C/C++!

Anyway, misuse of assert includes using it to assert on environmental factors (e.g. memory allocation, file existence, etc.), invoking it with a side effect based expression (e.g. initial assignment of a pointer), and also using a pointer argument (assert is intended to take an int, not a pointer). An example that illustrates all three:

FILE *fp;
assert(fp = fopen(name, mode));

In spite of a reasonable amount of education and guidelines, I found this and other examples in a few systems. Some of the misuses were quite creative and I must confess surprised me: I had such a narrow view of what was sensible use of assert that I never realised to what extent it could be abused!

It gets misused to the point that people are afraid to turn off NDEBUG in the release version for fear of breaking the system! Here we have a case that the tables are turned: assert has become a major liability. And how did it become so? Misunder-standing and miss-education. This is no slight on the authors, but there are some very experienced people whose recommendations represent classic misuses of this feature.

In short, most uses of assert found in systems are inappropriate, and leave Sturgeon's Law far behind in the rear view mirror. Surprisingly - now that I have long since been disabused of my naïveté - for just a single feature, assert is remarkably hard to use correctly and consistently.

If I could be sure that assert were used only as a correctness tool and was guaranteed not to be a liability, I would go back to recommending it for mixed teams. Otherwise, given a limited amount of time and effort, I prefer to concentrate on ensuring the understanding of other (commonly misused) constraint concepts in the language: types, const, inheritance, polymorphism, scope, etc.

Strange coincidence, I gave up assert about the same time as Kevlin. My reasons:

Proving some code is valid involves more than demonstrating that a (usually limited) set of test cases fail to execute an error trap.

Since the limits of what one can efficiently test are limited (e.g. there are many "invalid pointer" values other than 0) such tests lead to a false sense of security.

The code in the development build should be the same as that in the release build (that is the one that has to work)! assert defeats this.

There is an industry shortage of developers that use it correctly (checking preconditions/invariants) - too often I've seen horrors like:

assert(file = fopen("plover"));

A interview question that I used to ask was:

What's wrong with the following code fragment?

int *pInt = 0;
assert( pInt = new int[100] );
pInt[0] = 0;

To which an alarming number of candidates said 'nothing'.