To someone who uses code, it doesn't matter a fig what the designer was thinking. It matter what the code does. Then you can decide if it does something correctly enough to be usable in the state it's in.
Now, if what you're trying to do is distill some overall global design details from patterns you find in the code, you may or may not get lucky -- there may simply not be any, and the code was written in an ad hoc manner to solve a particular limited problem and not intended for more general use. The fallacy here is thinking that if the code does not follow the docs (if any), our "invester" can simply "blame the code" for being wrong. Doesn't get your program working, does it? Might give you an idea who to "sue for damanges", but unless you have pockets deep enough to mount a suit and "they" have assets enough to satisfy you, you are out of luck. Often the designer, programmer, and documentation writer are one and the same person, and the proper global design (and thus documentation) goals are not clear until some attempt at implementation. Agile development trumps waterfall design because you can never be perfectly right at each stage. Unfortunately, it makes documentation somewhat of a "catch up" activity. (Ideally, the docs are always correct but not necessarily complete, and completeness is achieved through global patterns rather than local exceptions thus reflecting the refactoring effort). More likely, it results in a series of design, implementation and REFACTOR. Do you keep your docs in sync at every step of the way, or do you wait until some semblance of stability has appeared in the refactor cycle? -----Original Message----- From: owner-openssl-us...@openssl.org on behalf of Mark H. Wood Sent: Wed 12/2/2009 6:42 AM To: openssl-users@openssl.org Subject: Re: General question about documentation 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.
