Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!watmath!clyde!burl!ulysses!allegra!mit-eddie!think!harvard!seismo!gatech!akgua!akguc!mtunh!mtung!mtunf!mtx5c!mtx5d!mtx5a!mat From: mat@mtx5a.UUCP (m.terribile) Newsgroups: net.singles,net.cse Subject: Re: Re: portable code Message-ID: <1249@mtx5a.UUCP> Date: Thu, 20-Mar-86 02:51:19 EST Article-I.D.: mtx5a.1249 Posted: Thu Mar 20 02:51:19 1986 Date-Received: Sun, 23-Mar-86 00:03:42 EST References: <653@moscom.UUCP> <569@hoptoad.uucp> <11569@watnot.UUCP> <1087@burl.UUCP> <6571@cca.UUCP> Organization: AT&T Information Systems, Middletown, NJ 07748-4801. Lines: 85 Xref: watmath net.singles:11113 net.cse:800 > >I have seen alot of assembly language programs some were comment extremely > >well and others extremely bad. Most of the bad ones were the ones which > >had a comment on every line. > >A great many of the well commented programs had enough comments to make > >code segments easy to understand, but they were far from the comment per > >line guideline which you mentioned. The problem with the comment-per-line is that it focuses you on the HOW and takes you away from the WHAT and the WHY. There are plenty of good ways to cumunicate the HOW. One can use abstract types, or the concepts thereof. One can use data representations tuned to the problem at hand, so that one page of code reduces to a line or two. And finally, one can write code with a sense of purpose. Just as prose can wander, or be coherent, code can be focused or diffuse. Code that is focused does all of one task before moving on to another. Code that is diffuse can't quite decide what subtask has to be completed first, so it does a snippet of this and a skoshe of that. Diffuse code will repeat a clumsy addressing operation several times in the course of a few lines. Coherent code will use compund-assignment operations, or compute the addresses once and store them in pointers whose simple, topical names tell WHAT, hint at WHY, and clarify HOW. Every comment advertises doubt: the code may not read clearly enough. Every comment admits to failure. Don't get me wrong ... I use plenty of comments. In my current assignment, I've been accused of writing tomes. Yet even those tomes are inadaquate. To address one important datum in the current system, starting from the basic data: which X in what unit of Y, takes about 65 characters of code, including two subscripting operations, five structure/union selections, and several explicit additions. And because some data are stored in parallel tables (because of valid powerfail protection requirements) this operation may have to be repeated! How in hell can you remember WHAT you're doing and WHY when you have to work that hard to describe the minutiae of HOW? > I also find that the thing that it is really important to comment are > the declarations. Repeat -- this is really important. The reason that > it is really important is that it forces you to have a well defined > meaning associated with each variable. In my experience (and I have > a lot of it) conceptually ill defined variables is the second most > common source of logic errors in programming (inability to think is > first. No smiley, unfortunately.) True. We have one situation where a datum has a type field, and a value of zero in that type field means that the datum is empty. The only problem is that in every blocked group of these things, several data at fixed locations have fixed types -- and the type fields for these are zero, just as if they were unassigned. Instead of being able to just look at the datum to decide what to do with it, instead of being able to address it once and pass a pointer to it to all things called below, we must pass the specific index of the datum in the block. We must also keep the block index around ... Instead of being able to test or switch or index a function or attribute table with the function code, we must also check the relative position of the datum to the beginning of the block. Literally hundreds of tests, maybe thousands, need to be done on the type field in different parts of this system. Every one of them must be between three and six times as complex as it ought to be with extra data to be hauled around and lost or mishandled, and every test on how to handle that troublesome datum must be built from a set of non-parallel cases. One must be able to see this stuff BEFORE it happens. The people responsible for this humpty dumpty mess were patting themselves on the back for having put a complex problem to bed when I came on the project. NO amount of schooling will teach you what working with 20,000 lines of well-designed code for six months will teach you. And not one of these people had seen more than two hundred lines of well-designed code in any six-month period. ``Any fool can criticize, condemn, or complain, and most fools will do just that.'' -Dale Carnagie ``Almost, at times, the fool'' T.S.Eliot, in The Love Song of J. Alfred Prufrock -- from Mole End Mark Terribile (scrape .. dig ) mtx5b!mat (Please mail to mtx5b!mat, NOT mtx5a! mat, or to mtx5a!mtx5b!mat) ,.. .,, ,,, ..,***_*.