public/private/stable/unstable

[Martin Pool]

On 8/27/08, John Arbash Meinel <john at arbash-meinel.com> wrote:
>  > And:
>  > _ means *either* is fine, as long as no review ever says "dont use
>  > symbol _GAM because its private" when the symbol is actually public but
>  > unsupported. So choosing "means either" will cause reviewers to know
>  > their symbols better, or cause them to stop commenting on usage of _
>  > symbols.
>  >
>  > -Rob
>
>
> My personal vote is for _ == either. It is simply a way to convey to people
>  wanting to use the api that we don't guarantee it will be preserved without
>  warning. A "use at your own risk" flag.
>
>  I believe Aaron has different feelings. He felt *very* strongly that
>  _iter_changes was never-ever supposed to be used by anyone without pushing to
>  get it "public" first. My feeling was that it was there, better than
>  everything else, and we just wanted some time to polish it before we committed
>  to backwards compatibility.
>
>  I've also never had much problem with making plugins compatible using
>  "getattr()" style handling.
>
>  Unfortunately, I think we need to wait another week for Martin/Andrew to come
>  back before we can get a consensus. And this is deep in a thread so they might
>  miss it.

I'm back, and did eventually find this.

If reviews are being bounced in the way Robert describes that's
clearly bad.  It may indicate a problem deeper than just the absence
of clear rules for an underscore prefix.

Who is meant to use an interface, just what scope you're talking
about, whether you can modify it or override it, and how much they can
rely on it to be stable is a lot of weight to hang on one character -
really just one Boolean bit.

For instance the case came up the other day that there was a very
non-public interface (readdir something) without an underscore.  The
module where it was declare had an initial underscore, but it was also
exposed in osutils without one.  So, is it private or not?

And of course if there is no public interface to achieve an
interesting goal, people are not going to not do it, but rather they
will use the private interface.  (Or at least I hope they will.)

At best the underscore gives people a clue to look for an alternative
interface.  But we don't necessarily guarantee there is a public
interface to do any particular task, or that it's efficient.  There is
not much feedback pressure at the moment to do this.

The feedback pressure we do get is "you broke X" and in fact we're
going to get that whether X is declared as public and stable or not,
unless there's some other good alternative.  It seems to me that we
rarely go back and say "X has been stable for a while, let's rename it
to be public."

We do deprecation warnings for some methods and this relates to how
they're named, but there is a fair amount of judgement.  For instance
we only consider people that might be subclassing, overriding or
otherwise modifying (as opposed to just calling) our classes when we
particularly expect someone to be doing it.  I'm not sure that
anything more is feasible.

In a statically-compiled environments we might have a hard distinction
between what's stable and public and the rest would be just hidden,
but that's probably a burden on our process and anyhow hard to enforce
in Python.

All in all my preference would be that people freely use _foo to
indicate something is relatively more private.  For example if it's
just a helper method intended to be called by the class's own
implementation, or a class intended only to be used by others in the
same module, _foo would be appropriate.  So it's almost a free choice
by the code author, and the most reviewers should be saying is "have
you thought about X".

Instead I'd say the energy should go into documentation either in the
docstring, the news, or the developer docs.  Like "you can override
this in a subclass to do blah" or "don't call this, use wibble()" or
"this interface is expected to change as we tune foo."

As in the mail from Kiko I just forwarded, if reviews are becoming a
point of contention we need to look at how much they're really helping
our QA and whether the emphasis should shift.  I'm finding I interpret
the "design and code clarity" criteria not as "is this as clear as we
can make it" or "is this clear enough" but "would I be able to
maintain this code?"

-- 
Martin <http://launchpad.net/~mbp/>