Parrot Design Documents in Need of Overhaul

Andrew Whitworth -- the fastest blogger in the East! -- has already blogged about our September 18 meeting in Fairless Hills, PA. He has received several responses to that post, as well as a more complete response from chromatic -- the fastest blogger in the West! whiteknight has responded in turn. Enjoy!

I'll let whiteknight, chromatic and others debate the question of Parrot's maturity -- or whether 'maturity' even makes sense in this context. Let me mention some ideas that came up during my conversation with Andrew last Saturday which he didn't dwell on in his blog post.

Incomplete Design

Whether or not Parrot is mature, I think most Parrot developers will agree that its design is incomplete. Our design is kept in Parrot Design Documents which appear in our repository in docs/pdds and docs/pdds/draft. 11 of our PDDs are sufficiently incomplete that they have never made it out of draft stage.

pdd01_overview.pod       pdd10_embedding.pod      pdd29_compiler_tools.pod
pdd05_opfunc.pod         pdd11_extending.pod      pdd31_hll.pod
pdd06_pasm.pod           pdd14_numbers.pod        pdd31_hll_interop.pod
pdd08_keys.pod           pdd16_native_call.pod

19 PDDs are official -- for some definition of 'official':

docs/pdds/pdd00_pdd.pod                 docs/pdds/pdd21_namespaces.pod
docs/pdds/pdd03_calling_conventions.pod docs/pdds/pdd22_io.pod
docs/pdds/pdd07_codingstd.pod           docs/pdds/pdd23_exceptions.pod
docs/pdds/pdd09_gc.pod                  docs/pdds/pdd24_events.pod
docs/pdds/pdd13_bytecode.pod            docs/pdds/pdd25_concurrency.pod
docs/pdds/pdd15_objects.pod             docs/pdds/pdd26_ast.pod
docs/pdds/pdd17_pmc.pod                 docs/pdds/pdd27_multiple_dispatch.pod
docs/pdds/pdd18_security.pod            docs/pdds/pdd28_strings.pod
docs/pdds/pdd19_pir.pod                 docs/pdds/pdd30_install.pod

But Andrew suggested that quite a few of the 'official' PDDs are actually out-of-date and/or incomplete. They no longer reflect the current Parrot implementation. Andrew suggested that this poses problems both for Parrot developers -- they don't provide a guide for implementing as yet unimplemented Parrot subsystems -- and for Parrot users -- they don't provide a stable, mature API on which outside developers can build projects.

Andrew went on to wonder, Are the PDDs capable of being forward-facing documents which drive the implementation rather than reflecting (inadequately) what we have already done? Are the PDDs worth the time and effort needed to maintain them?

Neither Andrew nor I pretend to have answers to these questions. But these questions forced me to realize: I have never read all the PDDs. And I'm willing to bet that you, the reader of this post, haven't read them either!

So, I know that I'm going to have to start reading the PDDs and coming to my own judgment about their adequacy. I know I'll be discussing them with project architect Allison Randal. And before long I will probably be suggesting that we have a design committee to conduct a thorough study of our PDDs and to overhaul them where needed.

pdd31_hll is forward looking

If it helps at all, pdd31_hll.pod is intended to be forward looking, describing an API for how things should work as opposed to describing existing practice. It's intended to replace pdd31_hll_interop.pod, which was never accepted as being the right way to go. I think that all that remains for pdd31_hll.pod to become "official" is for someone to declare it so.

Regardless, pdd31_hll_interop.pod should be deleted, which I've now done in r49249.