I was just starting to think about writing something on the history and
evolution of Parrot's design, and came across some PDDs in the mail archives.
Grief, I remember these things! These were meant to document the design,
what we'd decided, why those decisions were a bad idea, what we chose instead,
and so on. They were also supposed to help ensure that everyone knew what
we were working on and how it all fit together.
Needless to say, we stopped using them. This seems sad, and, after the recent
confusion (completely my fault) about how keys should be implemented, really
quite silly.
I know I'm the worst offender in terms of hacking the source without really
telling people what I'm doing, so I'm going to fix this by pushing out a
couple of PDDs in the near future.
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.
I don't want to single people out, because we've *all* been pretty crap about
this, but I notice we have a bignum implementation and bits of an IO subsystem
in there without any associated documentation. This, bluntly, sucks. Alex,
Melvyn, Ton, etc. I'd like to see PDDs for your stuff as soon as you have time
to write something. Start small, so we've got *something* to look at, and add
detail later at leisure.
On the other hand, I don't want to make PDDing an onerous requirement. Here's
what I propose:
1) All the PDDs go into the CVS repository (We give Ziggy CVS access so
he can tweak these where necessary.)
2) Brand new stuff has to have a PDD put in the repository *first* -
create a PDD, discuss it, send it to Ziggy and have him number it and put it
in the repository.
3) Patches which change the design of something also include a patch to
the PDD, which changes the version number and adds an entry to the "CHANGES"
section (adding it if it doesn't exist) stating either:
what was wrong with the old design and how you fixed it, (if you're
changing something)
or
what you've just done AND WHY. (if you're adding something)
oh, and a datestamp and email address thingy.
In case that's too onerous, just one or two lines saying what you did would
be better than nothing at all.
But please, let's use these things. I firmly believe that these will speed
up the process, rather than slow it down. At the moment, the way I want
certain things done is only stored in my head and Dan's head. This means only
Dan or I can implement them. If we share our ideas, other people can ship in
bits. If we're really lucky, Dan and I won't have to write any code at all. :)
Yes, I'm being an anal retentive asshole. It's my job.
Simon
--
"Do not meddle in the affairs of cats, for they are subtle and will piss on
your computer." --Bruce Graham
