api stability rules

[Robert Collins]

On Fri, 2006-01-06 at 12:26 +1100, Martin Pool wrote:
> This follows on from the conversation in December and recently about how
> to mark bzrlib interfaces that are promised to be stable in the future,
> so as not to break external code.  We're agreed that in general
> functions/classes with _-prefixed names should be treated as
> bzrlib-internal and avoided by external clients.
> 
> I talked to Robert a bit more.  The only area of disagreement is how to
> mark members of a class which shouldn't be relied upon by bzrlib
> clients, but can be used by bzrlib client code that is subclassing the
> class.  In other words, how to represent the equivalent of protected
> access in C++ or Java.  

Yup.

> What I propose is:
> 
>  * we try to give __names to make things genuinely private when they can
> be

Agreed.

>  * give internal or non-stable interfaces _names

Yup. But I'd we say it like '
  * Give supported interfaces 'names'. 

And just leave the use of _ as a not-really-defined thing for now. So
that we have room to wiggle as we refine this later.

>  * we defer a decision about whether or how to specially treat members
> that can safely be accessed by external subclasses but not otherwise;
> that is for the moment give them underscores or not just based on
> whether they're stable interfaces, regardless of their use in
> subclassing.


Rob
-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060106/66e2fc84/attachment.pgp