[Zope-dev] RFC: Python/Zope Interfaces

[Jim Fulton]

Dieter Maurer wrote:
> 
(snip)

> Let me stress my point of view. Maybe, we are not too far away
> from one another:
> 
>   * I like clear specifications (as you do)

Yup.
 
>   * The specification has more value, when its implementations
>     adhere to it (you probably will agree).

Well, not quite. If you use documentation of an interface to
figure out how to use an existing implementation, then I agree
that, for that purpose, an interface that documents the 
implementation accurately is valuable.

OTOH, if the implementation is doing the wrong thing, an interface
that documents doing the right thing is more valuable than an interface
that documents the wrong thing. Given an interface that documents
the right behavior, all I have to do is fix the implementation, 
which is easy. If both the interface and the implementation are
wrong, then I not only have to fix the implementation *and* the interface, 
but, much worse, I have to fix all the client implementations that
were written to the wrong interface.
 
>   * A documentation about an existing system is more
>     valuable, when it states what is rather than
>     what should be (here we may disagree).

It depends on the goal of the person using the documentation.
 
>     I usually start by studying the documentation.
>     If it descibes what is, then I will recognize
>     early what does not fit my requirements and
>     can work around it.
>     If it describes what should be, I will
>     determine the deficiencies much later in my projects,
>     modifications are much more difficult and expensive.

Or you could get (or help, as you often do, thanks) the author
to fix the broken implementation.
 
>   * Having the specification near the implementation
>     helps the implementors to adhere to it,
>     especially with long maintenance periods.
>     (Here we may disagree).

Yes, we disagree.
 
>     I believe in the value of well documented
>     source, in literate programming.

I agree with the value of well documented interfaces 
*and* well documented implementation, source.  I see alot
of value for documenting the implementation in the source.

I see *some* value of seeing the interface when writing and
maintaining the source. I'm really happier seeing a separate
specification. Perhaps this is a matter of taste.  

I wouldn't relish duplicating interface documentation in all of the
implementations that implement it and trying to keep them
consistent.

Jim

--
Jim Fulton           mailto:jim@digicool.com   Python Powered!        
Technical Director   (888) 344-4332            http://www.python.org  
Digital Creations    http://www.digicool.com   http://www.zope.org