Brainstorm, What constitutes a public API? (was Re: [Zope3-dev] Re: APIs breakage)

[Stephan Richter]

On Tuesday 13 July 2004 09:56, Jim Fulton wrote:
> - There be public interfaces and private interfaces.
>
>    Here, bublic or private doesn;t say anything about
>    security, but about the stability of and long-term
>    commitment to an API.
>
> - Public interfaces should be stable and hard to change.
>    They *can* be changed, but only through a gradual change process
>    involving deprecation warnings and a long period of backward
>    compatability.
>
> - Package 'interfaces' modules should *only* contain public
>    interfaces. This means that, when developing new sofware,
>    you should avoid ceating interfaces modules until you are willing
>    to carve an interface in stone.

I like all of the above and agree with them. I would like to add:

- Only objects (e.g. functions, variables, constants, attributes, ...) that 
are defined via an interface in '__init__.py' can be considered public. 

Note that we already do that with 'zapi' and 'component'. Only methods 
declared in 'IZAPI' or 'IComponentArchitecture' are available, though many 
more methods and attributes might have been defined in the module.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training