public/private/stable/unstable

[Robert Collins]

On Tue, 2008-08-26 at 20:30 -0400, Aaron Bentley wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Robert Collins wrote:
> > On Tue, 2008-08-26 at 19:52 -0400, Aaron Bentley wrote:
> >> I would like people to be able to tell, at a glance, when a method is
> >> completely safe to use.  I think requiring reading the docstring of
> >> every non _ method would be burdensome.
> > 
> > I think 'safe to use' is simply too complex to encapsulate in the method
> > name. More below.
> > 
> >> How about:
> >> _ -> unsupported-AND-private unless the docstring says otherwise
> >> no _ -> supported and public.
> >>
> >> So you'd signal unsupported-and-public using a _ with a docstring.
> > 
> > I'd be happy with this.
> > 
> > Won't this will force every method on internal objects to be _ prefixed
> > though?
> 
> I'm not sure what "internal" encompasses here.  For example,
> VersionedFiles is a stable API, but the VF instances on repositories
> ought to be considered private.

DataAccess, KnitIndex, ParentsProvider are all things that come to mind;
I'm sure there will be more. I don't consider VersionedFiles to be
'stable'. Its an API for the convenience of repository implementors -
repository objects expose it, and only users that know the internals of
a particular repository type should be accessing it or using it. I'm
sure it will grow to be really robust and stable. 

> So for them, constructing your own and doing what you like is fine.  But
> accessing a repository's _versionedfiles member would not be kosher.
> 
> For classes whose existence or signature is not guaranteed, constructing
> your own instance would refer to the class name, and that should have a
> _ prefix.

But construction may be arbitrarily far away from the bound variable
instance.

-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/20080827/493d1223/attachment.pgp