[Python-Dev] Breaking undocumented API

[Fred Drake]

On Tue, Nov 16, 2010 at 4:31 PM, Ben Finney <ben+python at benfinney.id.au> wrote:
> 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.

Agreed.

Many style guides are written as extensions of PEP 8 in particular.
This has already bitten the Zope community, which was developing style
beyond what was even written in it's own extension, only to have PEP 8
change out from under it in a contrary manner.

Lessons we learned:

- If you refer to someone else's documents, refer to specific versions.
  References can be updated explicitly if desired.

- If you have even an advisory point of style, write it down in the style
  guide, so people who read the foundational documents you referred to
  without version information will be aware of the expectations.

Otherwise, you may as well not have one.


  -Fred

--
Fred L. Drake, Jr.    <fdrake at acm.org>
"A storm broke loose in my mind."  --Albert Einstein