Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!watmath!clyde!burl!ulysses!mhuxl!ihnp4!zehntel!hplabs!sri-unix!gwyn@BRL-VLD.ARPA From: gwyn@BRL-VLD.ARPA Newsgroups: net.unix Subject: Re: Kernighan and Pike's book: a flame Message-ID: <307@sri-arpa.UUCP> Date: Sun, 22-Jul-84 23:03:28 EDT Article-I.D.: sri-arpa.307 Posted: Sun Jul 22 23:03:28 1984 Date-Received: Sat, 28-Jul-84 19:43:53 EDT Lines: 50 From: Doug Gwyn (VLD/VMB)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.