Kernighan and Pike's book: a flame

[trb at masscomp.UUCP]

>From down!pep:
>If 90% of the book's readers can improve the authors' coding style,
>then (sadly) the book has reached the wrong audience.

>But, I'm confused.  Why include comments in the sample programs when the
>surrounding text explicates the code?!  I'm sure the authors didn't intend for
>readers to skip the English text, reading nothing but the examples (what, no
>pictures?  not a single flow chart!).  On the other hand, I have yet to see a
>complex program so well-commented that it couldn't have been better explained
>in an accompanying text.

An example, by definition, is "one that serves as a pattern to be
imitated or not to be imitated. <a good ~> <a bad ~>"

Examples set by Kernighan and Pike are certainly examples that will be
followed.  The fact that the coding examples were elucidated in the
text would be no excuse for not making them production quality
examples.  I find Pat's statement odd, about her having never seen code
so well commented that it couldn't have been better explained in
accompanying text.  Comments in the code have the vital advantage of
locality.  If you cross reference the code with line numbers (like John
Lions did in his classic commentary on V6) and comment in a separate
text, you are also achieving that goal.

I think the question here is one of documentation logistics.  Most of
us see the uncommented code, and there's no elucidating accompanying
text.  If we had that commentary, we wouldn't complain.  If people are
going to comment their programs to explain intricacies in the flow of
execution, it's often best to do it right in the code, though overviews
and descriptions of features will be better off apart from the source.
How many of you grep for case labels in a C source, hoping to find
interesting hidden commands?  Keeping documentation useful and complete
is a goal that most of us only aspire to achieve.  (Document?  But I
have work to do!)

I think Pat is a bit flip when she ridicules the notion of pictures and
flow charts.  While there is nothing on this green earth stupider than
a flow chart which mimics a program line for line, a picture or chart
can help make it easier to understand high level flow and structure.

As a matter of my opinion, the coding style in K&P's book isn't as bad
as hpfcla!ajs led me to believe.  The hoc functions are small and each
one is identified with a comment.  The functions seem to perform atomic
actions, so commenting within them doesn't seem necessary.  Worse than
no comments are "a++; /* increment a */" comments.

Code must be commented (and written!) with care.  We should be arguing
about quality rather than quantity.  I think K+P's book was written
with quality in mind and in execution.

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