[Python-Dev] Breaking undocumented API

[Ben Finney]

exarkun at twistedmatrix.com writes:

> On 03:48 pm, guido at python.org wrote:
> >Hm. Apart from the specific semantics assigned by the language to
> >single and double leading (and trailing) underscores, I still think
> >this belongs in a style guide, not in the library manual.
>
> I don't think it belongs only in PEP 8 (that's "a style guide" you're
> referring to, correct?).

I don't know about Guido, but I'd be −1 on suggestions to add more
normative information to PEP 7, PEP 8, PEP 257, or any other established
style guide PEP. I certainly don't want to have to keep going back to
the same documents frequently just to see if the set of recommendations
I already know has changed recently.

Rather, I took Guido's mention of “this belongs in a style guide” as
suggesting a *new* style guide. Perhaps one that explicitly obsoletes an
existing one or perhaps not; either way, the updated normative
recommendations are in a new document with a new name, so that one knows
whether one has already read it.

> It needs to be front and center. This is information that every single
> user of the stdlib needs in order to use the stdlib correctly.

True enough. This is information that goes beyond a style guide for
writers, and into conventions that API users need to know also.

-- 
 \         “I went to the museum where they had all the heads and arms |
  `\      from the statues that are in all the other museums.” —Steven |
_o__)                                                           Wright |
Ben Finney