Kernighan and Pike's book: a flame

[trb at masscomp.UUCP]

hpfcla!ajs:
>Hmmm...  I'll be more  specific.  Opening to page 341 (at random, in the
>hoc  listing) we find a short  header  (three  lines)  followed by seven
>short  procedures.  Only one  procedure  has a summary  comment, a brief
>one.  There are no bold  headers to separate  and locate  routines,  nor
>comments to summarize the purpose of each  routine, how it fits into the
>overall  scheme,  what it's  limitations  are, etc.  On the whole page I
>count three blank separator lines.  There are very few comments and they
>are  quite   cryptic.  Variable  names  like  "d"  and  "fp"  are  used.
>Expressions are run together without blanks.
>
>This is  clearly  one code  fragment  that could  benefit  heavily  from
>ergonomic improvements in style, commenting, layout, vertical alignment,
>etc.  Unfortunately, it's typical of the book.

I think there's a commenting heuristic you're ignoring.  If it will
take a minute to figure out, then don't comment it.  The comment will
be obfuscatory and even disrespectful.  If it will take a week to
figure out (even an hour), then comment it.

Looking at page 341, you found a three line header followed by seven
short procedures.  When I looked at page 341, I took a minute to look
back at page 340 also, where there was another 20 or so lines of
commented headers which are part of the same file as the one on 341.
Matter of fact, this file goes through page 345, and that's evident after
less than 60 seconds of reading.

True Confessions time:  I have not carefully read the book (K&P).  Just
flipped through the pages.  I have not studied hoc for more than five
minutes.

Coming upon page 341, it is absolutely immediately evident to me that
the routines on this page deal with different kinds of tokens, probably
from a recursive descent parser.  The routines are stamped out of a
cookie cutter for the most part, and their names (initcode, push, pop,
constpush, whilepush, etc.) tell me exactly what I want to know.  When
there's a question, there's a comment.

If, as Alan suggested, there were bold headers to separate and locate
these routines, I would call it overkill.

The hoc listing looks like it's about 1000 lines long.  It looks
quite well laid out to me.  It would take longer for a person without
an undergraduate level background in compiler writing techniques to
understand the program, but that doesn't mean there's anything wrong
with it.

As for K&P's style, commenting, layout, vertical alignment etc., I find
the hoc listing quite pleasing in all these respects.  I wouldn't move
a single character.  You can rest assured that K&P both have had their
senses of aesthetics well formed over the years.  And you can look
at the acknowledgements in the preface to see who helped them out.
Those people too, have some sense of aesthetics.  If, in hoc, the
main example in the book, every character were not originally in
place, one of the acknowledged helpers would have pointed it out.  I
know I would have if I'd been proofreading it.

I agree with Alan that it's important to document arcane code.  I also
think Rob Pike's attitude (at least as it appears to me) about
commenting is a bit vainglorious.  I do think that Alan is barking up
the wrong tree when he attacks the hoc listing in the K&P book, I
think it's a very pretty piece of work.

There's definitely room for elegance in our craft.  Putting bold
headers between each token-routine on page 341 of the hoc listing
would be pretty disgusting.  Thank God that John Roebling didn't
design the Brooklyn Bridge with hpfcla!ajs's sense of aesthetics.

	Andy Tannenbaum   Masscomp Inc  Westford MA   (617) 692-6200 x274