At 4:18 PM +0000 2/17/02, Simon Cozens wrote:
>COMMITTERS PLEASE NOTE: I'd like you to ensure that any changes you commit in
>the future, whether by yourself or anyone else, has an associated PDD. When I
>say "any", I expect you to use your discretion - things to fix up warnings,
>typoes, minor alterations and so on don't need documentation to go along with
>them; changes which alter or create subsystems *do*. I consider this at least
>as important as tests, if not more so.
Also, be really, *really* clear on what's Design, what's Interface,
and what's Implementation. (Or, if you prefer, Concept, Blueprints,
and Execution)
Design is the high-level "How Things Work" or "What's my real
problem" piece. This is really the most important bit. If you've not
thought about Design, better start. Getting the design right is 80%
of the hassle.
Interface is what the outside of your thingie looks like to other
programmers. The interface should be stable, sensible, and really
really unlikely to change. Getting the interface right is about 14%
of the hassle. Interface generally flows naturally from a good design.
Implementation should be capable of being yanked out and replaced
with no notice, and things still work. It is, and should be,
considered ephemeral. It's the least important thing to get right,
since it can be fixed or completely replaced as we need to.
As an example, take a look at the memory allocation system.
The Design bit is "We are having a tracing, potentially compacting GC
of some sort, which places the following rules on the core". (The
rules being things like "All memory's anchored by buffer structs, all
buffer structs have to be reachable by PMCs, and suchlike things)
The Interface bit are the routines in resources.c and memory.c. The
interface isn't that complex, and pretty straightforward for the
problem.
The Implementation bit is essentially irrelevant. We started with the
code being wrappers around malloc and free. Now the memory itself is
allocated from arenas, and soon the PMC and buffer headers will too.
After that, a tracing GC will go in. None of the changes have made
any difference to the rest of the code once the interface was used
properly.
So, split things out if you're working on something new. Design
first, code last. It's a damn sight easier to fix a bad design before
you have code then it is to figure out what your design is and then
work around it after you have code.
The first person to say "But XP says code first!" will be summarily
mocked, as that's completely full of crap. You have been warned. :)
--
Dan
--------------------------------------"it's like this"-------------------
Dan Sugalski even samurai
[EMAIL PROTECTED] have teddy bears and even
teddy bears get drunk
