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