ajs@hpfcla.UUCP (07/05/84)
Seeing it praised here on the Net, I rushed right out and borrowed a
copy of Kernighan and Pike's book, "The Unix Programming Environment".
Well, it's not bad, and if you're not a wizard yet, it will point you in
some new directions. BUT...
As long as they took the trouble to build a soapbox, why the hell didn't
they use it to maximum effectiveness? Throughout the book they suggest
better ways of writing shell scripts and programs, and make subtle digs
at existing commands. Then they turn around and show off their own
efforts, which are sadly lacking. Hardly any comments; typical terse
styles; not enough bulletproofing. They don't even measure up to the
Indian Hill Style Sheet!
(Now, the IHSS has some problems too, but they're so far advanced that
I'd willingly admit they are religious issues. Meanwhile, I suspect
that 90% of the readers of K&P's book could dramatically improve the
authors' coding style, if they tried.)
In summary: Read, or at least skim, this book if you get a chance. But
remember that you can do much better when writing programs of your own.
Use lots of comments, including big block headers! Declare every
variable on a separate line, and explain it. Break your source up into
lots of small sections of only a few lines -- don't run it all together.
Give a damn!
Thanks for listening,
Alan Silverstein, Hewlett-Packard Fort Collins Systems Division, Colorado
{ihnp4 | hplabs}!hpfcla!ajs, 303-226-3800 x3053, N 40 31'31" W 105 00'43"pep@down.FUN (07/12/84)
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. Did we read the same book? My copy shows variables declared and commented one per line (e.g., see p. 262). Umm, maybe they don't conform to the IHSS (I wouldn't know, I haven't seen it). I understood the examples as presented, so I'm sure I don't care. Of course, you *did* say this was a flame, so you needn't cite any specific examples or evidence in support of your rantings. I bought a copy of "The UNIX Programming Environment", not "The Elements of Programming Style", and certainly not a soapbox. Pat Parseghian Princeton University, EECS Dept.
trb@masscomp.UUCP (07/13/84)
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
ajs@hpfcla.UUCP (ajs) (07/14/84)
> 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. 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. > 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. So who's yelling for quantity over quality? I agree, their book was written with that in mind. My flame was and is that they did not go far enough. In my opinion, all programmers are human beings, and all human beings are imperfect, and lazy too. That includes me. But, I strive, as a professional software designer, to make my software as "perfect" as it can be -- bug-free, ergonomic, portable, even pretty. I have two great frustrations: (1) With such an attitude you find yourself continually improving. Yesterday's code is always an embarrassment, lacking "obvious" improvements. Being human, you can never even come close to perfection. People can always find flaws in your code. (2) Most other people care far less about their overall code quality, and I often have to maintain it. Arggghhh... Alan Silverstein, Hewlett-Packard Fort Collins Systems Division, Colorado {ihnp4 | hplabs}!hpfcla!ajs, 303-226-3800 x3053, N 40 31'31" W 105 00'43"
gwyn@BRL-VLD.ARPA (07/23/84)
From: Doug Gwyn (VLD/VMB) <gwyn@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.
trb@masscomp.UUCP (07/23/84)
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
ian@utcsstat.UUCP (Ian F. Darwin) (07/26/84)
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...
Thanks, Andy. You saved me the trouble of writing a long, detailed
response to hpfcla!ajs. I'll just say that I agree pretty much
with Andy's response.
--
Ian Darwin, Toronto
{ihnp4|decvax}!utcsstat!ian