Subject: Re: docs
From: Dom Lachowicz (cinamod@hotmail.com)
Date: Thu Apr 19 2001 - 21:28:10 CDT
Paul wrote:
>Wow. I've been out of school *way* too long. I'm used to projects where
>there's no written record of any sort. To have large chunks of the design
>fleshed out even *once* in writing is, in my experience, a rare and
>precious
>thing.
I've actually learned this from my various jobs, not school ;-) I've learned
(the hard way) that Spec/Doc is absolutely essential to a project. No way
around it.
> >All we have now is
> >basically Jeff going "well, I'm going to write 6 pages of fluffy
>quasi-spec
> >on a 30,000 LOC implementation of a piecetable."
>
>Jeff was kind. He's good enough to have written a *damn* impressive 30,000
>LOC without telling you anything about it it all. The spec corresponded
>with the first few days of thought on the subject. Then he implemented the
>rest and refined it until it did everything it does now.
It is impressive. But from a maintainance viewpoint? Absolutely horrible.
Considering that I want to rewrite a new backend, knowing some of his
throughts/assumptions in english (not C++) would be extremely helpful.
>Considering the extreme rarity of true bugs in the code he wrote, I have
>zero problem with that. I'd certainly rather have all the code and half
>the
>docs than the other way around.
I'd rather have both. And half is being generous.
>We wanted to prove it could be done, and we did a damn good job at it.
Hell yeah!
>Oh, it certainly makes life easier -- if the docs are maintained
>scrupulously, that is. Bad docs are worse than no docs, until you realize
>they're wrong, at which point they become useful again.
Painful agreement here.
>There's no way around it ... it's work to have to drop into a codebase of
>between 100K and 1M LOC and find your way around. It's a skill anyone in
>the business learns, though.
True. The learning curve drops though, provided with the proper tools.
That's all I'm saying.
>Paul
>motto -- an implementation is worth 1000 words
Dom
motto -- most times, 1000 description do more to help understanding than
30000 lines of implementation - and faster, to boot
_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com
This archive was generated by hypermail 2b25 : Thu Apr 19 2001 - 21:28:39 CDT