At 08:52 PM 4/19/01 -0400, Dom Lachowicz wrote: >Thanks a lot. I know that you're a huge advocate of mailing-list discussion, >searching back through threads to find docs/design decisions isn't exactly >pleasurable. 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. >We're seriously lacking all sorts of docs on the underlying >design of Abi. Jskov has done well to get us at least inline Doxygen >comments as a standard. There should also be more docs lying around (maybe >with UML or Pics) about many/all of the design decisions. All of those would be (and are) nice to have. >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. 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. >The (unfortunate) short >story is that if we had to deliver this product to a client complete with >Doc/Spec, we'd get sued. Naw. Someone like that never would have funded this effort in the first place. And they certainly wouldn't have paid for specs or docs. The only reason this product exists at all is that people like Jeff and I went ahead and coded like banshees for the brief window of time that someone *was* willing to pay us. We wanted to prove it could be done, and we did a damn good job at it. >Why is this important? Well, who here helped Jeff write the PT? XAP vs. AP? > >/me searches for hands in the crowd > >Ok, so really no one besides Paul, who is an invaluable resource BTW :) So >being the new developers/maintainers, it is absolutely *essential* to have >these things lying around. 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. 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. Paul motto -- an implementation is worth 1000 words
