[Python-Dev] Breaking undocumented API (original) (raw)

Guido van Rossum guido at python.org
Wed Nov 17 16:52:37 CET 2010

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)

More information about the Python-Dev mailing list