ignatz (06/12/82)
Greg Davidson suggests that "A (sic) of a good programmer, writing in a decent high level language (e.g., Pascal, Modula-2, even ada and LISP [ augmented with appropriate macros]) is self documenting..." Oh, come on! I've heard this song before, and, Children, don't listen to the nice man who suggests that raw, unadorned code with NO comments is sufficient to describe any program longer than 3 lines in ANY language. It results in lost linkages, confusing data structures, etc. I don't care how long or flexible the identifiers for a language are; they can't describe the macro (in this case, meaning overall) function of the code segment, routine, program, or system. I consider a properly documented program to have a lengthy, non-technical paragraph describing the purpose of the thing's very existence, and its effects in a general way. Following this should be an involved discussion of invocation, options, etc.--a sophisticated user's guide, from which the published documentation is extracted. Finally, a detailed and technical discussion of the design theories behind the system, linkages, etc. should follow. Thereafter, in the main routine and every subroutine, each variable used should be named, along with its purpose in this routine; "calls" and "called by" sections, to describe who invokes this routine, and who it invokes; and a change history, so that the ongoing changes are recorded. ALL AS COMMENTS IN THE CODE. True, this descriptive stuff can get out of phase with the code--if the programmers let it. True, it takes up valuable storage space--but at least it, and the code, are ALWAYS together. And you have guaranteed that some poor schmuck doesn't spend hours poring over the code in dozens of modules, trying to put the whole mess together and figure out that "atoddata" stands for "analog to digital data structure". Granted, I have generated code that doesn't follow these standards; I don't defend that, though. I try to keep such code out of the public's hands until I can document it. And I indulge in pangs of guilt as I write it. "Nobody's perfect. We live in an imperfect world; however, our fate lies not in bemoaning the imperfection of the world, but in attempting to make it a little less imperfect." (No, I can't remember who said it.) Greg, I'm not keelhauling you. This is an attitude that has been taught and touted by respectable people. It's just that, after years of trying to unravel such code, I --and many others-- have come to realize that, as much as clear, concise code and well-chosen identifiers can help, something more is needed. Please don't feed this delusion. People need no encouragement to not write documentation. Dave Ihnat Analysts International Corporation contracted to Bell Telephone Labs Naperville (Indian Hill) IL ihuxl!ignatz (312) 979-6747
djmdavies (06/12/82)
I agree; code as such is rarely self-documenting to anyone other than the author for the next three days (or thereabouts), and only if under one page. In fact that applies even (usually) to code with imbedded comments of the usual kinds--specific to the local statements. What I find is most critically needed on any program source of more than a page is a high-level overview of what the program is all about, and generally how it is structured. Especially documentation of any data structures involved. Someone, I forget who, said that if you really understand the data structures in a program, then you understand the program. Though that obviously cannot be true for applicative programming styles. I'm not especially interested in listings of variables and where used, as such; that sort of thing ca be got with automated tools when one really needs it. Julian Davies, univ. Western Ont.
wagner (06/14/82)
WRT Julian Davies comments: I think the quote he was thinking of went something along the lines of "Show me your code, but hide your data structures, and the meaning of your program remains elusive. Show me your data structures but hide your code, and the meaning becomes clear." I recall it being in the introduction to a data structures text book, but I have just been through all of mine that arent hiding under papers and junk on my bedside table, and I cant find it. Sorry. Michael Wagner, UofToronto Computing Services