Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!zaphod.mps.ohio-state.edu!samsung!uunet!aria!dumbcat!marc From: marc@dumbcat.sf.ca.us (Marco S Hyman) Newsgroups: comp.object Subject: Re: Documenting OO Systems Message-ID: <285@dumbcat.sf.ca.us> Date: 9 Apr 91 03:53:38 GMT References: <4693@osc.COM> Organization: MH Software, Hayward, CA. Lines: 24 In article jls@rutabaga.Rational.COM (Jim Showalter) writes: Code not deliberately written to be as readable as possible by others is evidence of bad instincts run amok, and part of the reason software maintenance costs so much (any managers out there want to show a higher profit?--encourage better programming technique). Jim shouldn't be so narrow here. Programming technique is well and good but the real key is encouraging the programming staff to write, in whatever human language is appropriate, about the system being programmed. The programs easiest changed are those where not only the "what" is captured (as lines of code), but the "why". For an excellent example of this (as well as an example of picking the right tool for the job) see Jon Bentley's Programming Pearls column in the June '86 issue of Communication of the ACM. In it is a beautifully documented program by Don Knuth written in WEB -- and the (some might say hard to read :-) 6 line UNIX shell script that does the same thing. Ada, C, C++, SmallTalk, Assembler... None of them are right. All of them are right. Use the proper one for the given job. -- // marc // home: marc@dumbcat.sf.ca.us pacbell!dumbcat!marc // work: marc@ascend.com uunet!aria!marc