Kernighan and Pike's book: a flame

[gwyn at BRL-VLD.ARPA]

From:      Doug Gwyn (VLD/VMB) <gwyn at BRL-VLD.ARPA>

Aaaagh!!  Enough of this nonsense!

Alan Silverstein opened Kernighan & Pike "at random" to p. 341 and
criticized the code listing he found there.  Apart from the fact that
that code module listing started on p. 340, where almost every line
was commented (!), he ignores the fact that his random page is just in
an appendix where all the "hoc6" code was collected in one place for
ease of reference.  An entire chapter (Chap. 8) was devoted to
extensive comments about the "hoc" code, and the same routines that
are found on p. 341 appear on pp. 262-263 with additional comments,
as one would expect them to appear in production source code.  In fact,
p. 341 is about the least well commented in the whole appendix, making
me suspect an oversight in collecting the edited sources for the listing.

The variable name "d" means "datum", as is obvious from its declaration
in the source; similarly "fp" means "frame pointer", as again is quite
obvious in the source.  One could object to short names only if their
meaning was unclear.

A certain amount of study is necessary when maintaining any significant
source code.  Comments can help in the following ways:
	- indicate general functions being performed, so that one's
	  attention is directed to the appropriate code for further
	  study;
	- anticipate questions that the maintainer may have and provide
	  answers to them; e.g. "what is this variable used for?",
	  "what is the loop invariant?", "what assumptions are being
	  made that are not obvious from the function usage?", etc.
Meaningful variable and function names also help in understanding the
code.  The best aid, though, is a correct functional partitioning in
the original code design.  I give Kernighan & Pike high marks for this.

It is certainly true that the "hoc6" code as listed in the appendix
should be improved somewhat if it were the only internal documentation
for the program.  However, taken with the 55 pages of commentary this
must be one of the best-documented codes in existence.

It is also true that much UNIX source code (from both Bell Labs and
Berkeley) is poorly written, and I am sure that your code and mine
can be greatly improved too.  I support the call for quality code;
however, there is the danger of spending more time than is economically
warranted in trying to make code as pretty as possible.  One has to
decide what is "good enough" to support the code's life cycle and
stop improving it when he reaches that point.

If one can re-read his code of a year ago and be thankful for the
helpful way in which it was written, then he knows that the way that
he codes (not necessarily its basic design) is good enough.