On 25 September 2012 19:05, Rafael Schloming <r...@alum.mit.edu> wrote:

> Ken already wrote a bunch of documentation on this, perhaps he could post a
> link?
>
> Also, if you run 'make docs' you can see all the doxygen for the engine
> APIs.
>
> While I agree we need more documentation, keeping the C and Java impls in
> sync is a separate matter. Documentation as a functional spec is really
> only useful if it reaches the level of a formal specification that never
> changes, however that's just not realistic for us.
>
> Besides, we already have a much much more powerful tool for keeping the
> implementations in sync. We have the python test suite that will run
> against both implementations and tell us precisely where they differ. I
> really would like this test suite to be the formal spec, and like
> everything else it could certainly use more documentation, but it's quite
> capable of keeping the implementations in sync without that, and more
> importantly unlike a static document, we can drive changes in the
> functional spec that might be motivated by either the C or Java or JS impl
> back into this test suite and spread them to the other implementations much
> more quickly than we can with just a document.
>
> If there are problems with that model, or if the test suite is somehow
> insufficient, I'd really like to know. I know Rob has mentioned that the
> tests need to be more granular, some of them are a bit monolithic because
> they are trying to reproduce a very specific set of behaviour. For the new
> stuff I've been adding I've been trying to keep things as granular as
> possible.
>
>
To expand here a little... I think defining the functional spec via the
tests is both sensible and powerful. However, for this to work, each test
need to clearly correspond to a single piece of functionality that should
be common across all implementations; and the tests must be *much* more
comprehensive than they are currently. Moreover we should be developing the
tests in advance of actually implementing in either C or Java (or - when we
get to it - JavaScript).

In general I feel that we should first be agreeing the scope of
functionality on the list, then agreeing the API / detailed functional spec
via the definition of tests in the Python test suite (with reasonably
comprehensive documentation as to the functional requirement behind each
test), and only then attempting to implement across the various languages.
I feel like we are currently defining behaviour via implementation which
may be sustainable in the short term, but probably doesn't scale if we are
expecting a larger community to be contributing to the project.

-- Rob




> --Rafael
>
> On Thu, Sep 20, 2012 at 3:45 PM, Rajith Attapattu <rajit...@gmail.com
> >wrote:
>
> > We should seriously consider documenting the Engine API and it's
> > expected behaviour.
> > This has several advantages.
> >
> > 1. Use that as a basis for a functional spec, which we can then write
> > tests to verify the implementations.
> >
> > 2. Helps developers to navigate and understand the code more easily.
> >
> > 3. Finally we need this documentation sooner than later to accompany
> > our releases to for the end users
> >
> > 4. Helps to keep both C and Java impls in sync. We should probably
> > modify the doc before we change the code to ensure the doc is kept
> > current.
> >
> > Any takers ? (Looking at Rafi :D)
> >
> > Regards,
> >
> > Rajith
> >
>

Reply via email to