On Tue, Dec 01, 2009 at 02:08:08PM -0800, Randy Turner wrote: > As an investor, I would rather have my coders use a product with > documentation to "make progress" on the actual goals of the product, > rather than reverse-engineer the information they're trying to look > for. > > With the former method, my cost is (n), with the latter method, my > cost could be unbounded, depending upon how complex the source code > is (i.e., explicit code, or 14 levels of indirection and C macros > that have to be understood). > > It sounds like you're making the case for documentation to me....and > I agree.
Hear, hear! I've done such reverse-engineering. I once disassembled the compiled code (all there was on the Unsupported tape) for the TOPS-20 Programmable Command Language; edited it (through many iterations) into clean, idiomatic, well-commented MACRO-10; studied how it hooked into the EXEC; and from the coments wrote a user's manual, so I could figure out what the heck it did. I'm quite proud of my work. I never, EVER want to do anything like that again. It was lengthy and exhausting and ultimately unsatisfactory. Along the way I learned all the way down to my toes how little information is conveyed by code about what the designer was thinking or how he expected his design to be used. That's why, in a commercial OS, right next to each Reference Manual there is a Programmer's Guide or a User's Guide. I wish I *could* write some of the Programmer's Guides I have wanted over the years but, obviously, the person who needs one is the person least able to write one. My PCL manual, proud as I am of it, was a botch, much too short and incomplete. I simply wasn't able to glean enough information from the source to write properly. The designer knows things the rest of us do not, and it is precisely that knowledge which gives documentation much of its value. -- Mark H. Wood, Lead System Programmer mw...@iupui.edu Friends don't let friends publish revisable-form documents.
pgpwKJpF5MXBS.pgp
Description: PGP signature
