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

[Barry Warsaw]

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.

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.

[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.

Cheers,
-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20160510/02ef4526/attachment.sig>