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

[Casey Duncan]

On Tue, 13 Jul 2004 09:56:15 -0400
Jim Fulton <jim at zope.com> wrote:
[..]
> OK, let's brainstorm.
> 
> I suggest:
> 
> - 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.
> 
> Thoughts?

Since we are brainstorming: Maybe public interfaces should derive from a
"PublicInterface" marker interface, instead of just plain Interface. I
see two benefits to this:

- When reading the code, this is obvious and unambiguous and doesn't
rely on location conventions.

- Tools can introspect interfaces to easily determine which ones are
public.

OTOH, this would be a lot of bookwork to implement and maybe isn't a big
enough payoff.

-Casey