[Python-ideas] Is PEP 8 a style guide or API design? (was Re: Boolean parameters guidelines)

[Guido van Rossum]

On Tue, May 10, 2016 at 8:38 AM, Barry Warsaw <barry at python.org> wrote:

> On May 10, 2016, at 05:08 PM, Koos Zevenhoven wrote:
>
> >One advantage of "PEP 18" might be that many style issues don't affect
> >API design. And API design is more critical than style within the
> >implementation, because the former can be very difficult to improve
> >afterwards. And a shorter document may be easier to maintain in a
> >self-consistent manner and to understand by the reader.
>
> Let's be specific about PEP 8.  What is "style" and what is "API design"?
> IMHO:
>
> * Code lay-out: style
> * String Quotes: style
> * Whitespace in Expressions and Statements: style
> * Comments: style
> * Version Bookkeeping: style
> * Naming Conventions: style & API intertwined, perhaps[1]
>   - Designing for inheritance: API[2]
>   - Public and internal interfaces: API[2]
> * Programming Recommendations: style[3]
>   - Function Annotations: style[4]
>
> In short, I think style issues are those that you could imagine a tool
> enforcing <wink>, while API design issues are more for when humans
> communicate
> intent to each other.  That's not a hard-and-fast rule, but I think it gets
> pretty close.
>

I don't like that distinction, wink or no wink. It's not about whether you
can mechanically enforce it (this is why I am pushing for the rename of the
pep8 tool). E.g. how would the tool know whether a particular name is meant
to be private?

I think style issues are stuff that makes all code more readable. Naming
conventions definitely fall in that category (they hint at what kind of
thing something is when you see it used without having to look up the
definition right away).

I actually agree with your categorizations -- we can discuss inheritance
vs. composition until the cows see blue in the face, but it's just much
more complex, and it doesn't affect readability -- it affects what happens
when large systems built out of diverse components evolve.


> So really, the major of PEP 8 does belong in a style guide.  I'm not sure
> whether it's better to separate out the bits of API recommendations into a
> separate PEP, rather than perhaps reorganize or simplify PEP 8.
>

I vote for keeping it together but I also vote to keep the more complex API
design issues out of the PEP series altogether. Maybe 10 years from now
there's a bunch of blog posts with sufficiently broad acceptance that we
can add it to the PEPs, but until then I think it's pointless to try and
pretend there's much of a standard there (given that even PEP 8 has some
controversial bits and occasionally changes). Until then I recommend that
everyone watches Josh Bloch's talk on API design yearly. (
https://www.youtube.com/watch?v=heh4OeB9A-c; you can find other versions
and slides via this search;
https://www.google.com/search?q=josh+bloch+api+design&ie=utf-8&oe=utf-8)


> [1] But I would argue that the naming conventions section is more aligned
> with
> style and *if* a PEP 8 split were to occur, the majority of this section
> would
> stay in PEP 8.
>
> [2] With a dash of style.
>
> [3] With a pinch of API
>
> [4] I put this in the style category because it doesn't make
> recommendations
> to *use* function annotations.
>

This feels like unnecessary use of footnotes...

-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20160510/cfea004d/attachment-0001.html>