[Python-Dev] Breaking undocumented API

[Guido van Rossum]

On Tue, Nov 16, 2010 at 1: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.
>
> 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.

That's not what I meant. In the case of style guides I think it is
totally appropriate to update the PEP as new rules are developed or
existing ones are clarified (or even changed).

I certainly don't want to get into the situation where the style guide
is spread over multiple documents that need to be taken together to
make sense. It's not like PEP 8 specifies an API that is going to
break code in the future -- it is a set of conventions. You could
create a new PEP or move the style guide out of the PEP system (a not
unreasonable option) but the effect of changes to the style guide is
the same: some fraction of old code will become non-compliant. So
what? A style guide is just that -- a guide for coding style. Every
good style guide contains an escape clause: in PEP 8 it is the section
named "A Foolish Consistency is the Hobgoblin of Little Minds".

I've seen many unreasonable uses of style guides. This is a recurring
theme with Google's internal style guides too. For example, some
people get in an argument with a code reviewer about what's the best
way to do something, and they can't agree -- so now they want a
resolution in the style guide, no matter how specific their argument
is to one particular context. Other people claim you cannot change a
style guide because it would make existing code unnecessarily
non-compliant. There are the people who insist that the style guide be
followed mindlessly, even in situations where using a different style
would be clearly better. Then there are the people who want to update
the entire code base to become compliant after each style change.
Etc., etc.

All I want to say is, people lighten up. The style guide can't solve
all your problems. You are never going to have all code compliant. Use
the style guide when it helps, ignore it when it's in the way.

Finally, there's the issue of the scope of PEP 8. Its heading says
that it applies to the stdlib. The reason I put this in was so that
3rd party developers who disagreed with (part of) PEP 8 would not feel
obligated to follow it. At the same time I would hope that most people
see its value and follow (most of) it for their own code, accepting
that a more universal set of conventions helps readability of all
code. I would not be against changes to the style guide that emphasize
that some rules apply specifically to the stdlib (the rules about
mostly not using non-ASCII characters come to mind) and even to
include some normative rules for stdlib developers (e.g. exactly how
to use __all__ and private names).

But we cannot hope that all stdlib modules will all look exactly
alike. It is the work of many contributors, over many years, with
different backgrounds and intentions. That's fine. Let's try to make
new stdlib modules use the best style we can think of, but limit the
time spent fretting over code that's already there.

-- 
--Guido van Rossum (python.org/~guido)