C Programming Style -- New thought ("writing code")

[Peter Curran]

Ed Nather asks if anyone still writes code on paper.

I most certainly do.  And hack it and fiddle it and juggle it until
I am satisfied that it accurately reflects the abstractions I am trying
to express before typing it in.  I also make listings fairly regularly,
so I can assure myself that I haven't lost the forest in the trees (of
course, I might lose the trees in the paper :-).)  When I have worked
with code that was developed without listings, I usually find it makes
sense in small (e.g. screen-sized) segments, but the large-scale flow
is almost incomprehensible.

Since I've started this, I might as well add the the general commotion...

I think it is ridiculous to discuss the "readability" (really I mean
"understandability") of isolated lines of code.  Any code is unreadable
without some training (give your most readable example to an English
major), and quite easily readable with a bit of training - and no doubt
the training varies a little bit with the language, the style, etc.

The concern should be with global readability.  I pay particular attention
to two aspects of this - program organization, and commenting.

Programs should be organized as functions, each with a simple purpose.
Generally speaking, that purpose can be expressed in a single sentence,
having one of three forms - "do this," "do this to that" or "do this to
that using this."  Using the well-known result from cognitive psychology,
the function should consist of seven plus-or-minus two "steps."  A "step"
is not well defined, but I find it averages about 4 lines of code.
Being somewhat weak-minded, I also aim for about 5 steps whenever possible.
By a remarkable coincidence, allowing for a blank line between each step,
this results in a typical function occupying 5*4+4 = 24 lines - a screenful.

Now to commenting.  Comments should first state the purpose of the function,
then give the steps that are being performed (i.e. the abstractions that the
code is realizing).  If there are comments at all in a piece of code, they
usually tend to describe the realization.  Given the abstraction that a few
lines of code are realizing, I can usually understand the code.
However, it is much harder to figure out the intended abstraction, given
an understanding of the realization.  And understanding the abstraction is
essential to understanding the next-higher-level abstraction (i.e. the
function that calls the one being studied.)