On 25 September 2012 19:05, Rafael Schloming <[email protected]> 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 <[email protected] > >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 > > >
