From: utzoo!decvax!harpo!ihnss!ihuxl!ignatz Newsgroups: net.misc Title: Self-documenting code???? Sheesh! Article-I.D.: ihuxl.166 Posted: Fri Jun 11 18:52:17 1982 Received: Sun Jun 13 01:57:41 1982 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