<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Tue, May 10, 2016 at 8:38 AM, Barry Warsaw <span dir="ltr"><<a href="mailto:barry@python.org" target="_blank">barry@python.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On May 10, 2016, at 05:08 PM, Koos Zevenhoven wrote:<br>
<br>
>One advantage of "PEP 18" might be that many style issues don't affect<br>
>API design. And API design is more critical than style within the<br>
>implementation, because the former can be very difficult to improve<br>
>afterwards. And a shorter document may be easier to maintain in a<br>
>self-consistent manner and to understand by the reader.<br>
<br>
Let's be specific about PEP 8.  What is "style" and what is "API design"?<br>
IMHO:<br>
<br>
* Code lay-out: style<br>
* String Quotes: style<br>
* Whitespace in Expressions and Statements: style<br>
* Comments: style<br>
* Version Bookkeeping: style<br>
* Naming Conventions: style & API intertwined, perhaps[1]<br>
  - Designing for inheritance: API[2]<br>
  - Public and internal interfaces: API[2]<br>
* Programming Recommendations: style[3]<br>
  - Function Annotations: style[4]<br>
<br>
In short, I think style issues are those that you could imagine a tool<br>
enforcing <wink>, while API design issues are more for when humans communicate<br>
intent to each other.  That's not a hard-and-fast rule, but I think it gets<br>
pretty close.<br></blockquote><div><br></div><div>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?<br><br></div><div>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).<br><br></div><div>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.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
So really, the major of PEP 8 does belong in a style guide.  I'm not sure<br>
whether it's better to separate out the bits of API recommendations into a<br>
separate PEP, rather than perhaps reorganize or simplify PEP 8.<br></blockquote><div><br></div><div>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. (<a href="https://www.youtube.com/watch?v=heh4OeB9A-c">https://www.youtube.com/watch?v=heh4OeB9A-c</a>; you can find other versions and slides via this search; <a href="https://www.google.com/search?q=josh+bloch+api+design&ie=utf-8&oe=utf-8">https://www.google.com/search?q=josh+bloch+api+design&ie=utf-8&oe=utf-8</a>)<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
[1] But I would argue that the naming conventions section is more aligned with<br>
style and *if* a PEP 8 split were to occur, the majority of this section would<br>
stay in PEP 8.<br>
<br>
[2] With a dash of style.<br>
<br>
[3] With a pinch of API<br>
<br>
[4] I put this in the style category because it doesn't make recommendations<br>
to *use* function annotations.<br></blockquote></div><br></div><div class="gmail_extra">This feels like unnecessary use of footnotes...<br clear="all"></div><div class="gmail_extra"><br>-- <br><div class="gmail_signature">--Guido van Rossum (<a href="http://python.org/~guido" target="_blank">python.org/~guido</a>)</div>
</div></div>