----- Original Message -----
> From: "Rob Godfrey" <rob.j.godf...@gmail.com>
> To: proton@qpid.apache.org
> Sent: Tuesday, September 25, 2012 3:19:23 PM
> Subject: Re: Engine API
> 
> 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
> 
> 

The reason the python tests *won't* work as a spec are precisely
because they cannot "correspond to a piece of functionality". 

The tests are really good at what they do: verifying that functions
work as expected. Keep them coming. 

But the tests are lousy at specifying what can be done. I pulled up
messenger.py as a random example.
1. Not a single comment.
2. Magic numbers.
3. Magic process flow (setup, teardown part of some framework 
unrelated to messenger. What's with assert? What's the thread model?).
4. No enumeration of functions to call, function arg lists, arg
defaults, arg units, and so on.
5. What are prerequisites?

As a counterexample to using tests as specs, take a look at
cpp/src/tests/acl.py and tell me how C++ broker ACLs work.
No amount of ACL python test code will be a decent spec from
which users can understand and write ACL rules.

-Chuck


> 
> 
> > --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