tl;dr -- How should style guides evolve?
So this is a post inspired largely by a thread that popped up today [1], and specifically Alex's message [2]. I didn't want to derail that conversation (specifically dealing with style checking / correcting as a part of the standard library), but I did want to start a separate thread for an idea that's been rattling around in my brain for a while now. (Disclaimer, I am the current lead maintainer of the pep8 package, so part of this comes from my work there.)
Namely, how should style guides, and here I'm particularly looking at PEP-8, evolve?
I was influenced early on in my Python learning by a number of youtube Python conference talks. In particular "A Python Æsthetic: Beauty and Why I Python" by Brandon Rhodes [3] and "Transforming Code into Beautiful, Idiomatic Python" by Raymond Hettinger [4] had quite an impact on my thinking while I was moving from C / C++ to Python a couple of years back, and I highly recommend them.
Somewhat of an open question, I'm not sure I have a particularly hard and fast opinion on this issue, and I'd love to get feedback from the community. In particular, a couple of points that are worth mentioning:
* There are a number of checks that are disabled in pep8 by default, due to their being somewhat controversial for many users [5] which you can read about what each of them are for in the docs [6] if you're interested.
* Even within the checker community, there is some discussion about whether the tool should be rigidly set by the PEP-8 document (I tend to think it should be) and what that means for folks that don't want to follow a rule (I just disable it in my code) (see discussion about the use of ``isinstance()`` at [7]).
* There are several large code bases, the Python stdlib and Twisted for starters, that don't necessarily follow PEP-8 to the letter, due to pre-dating PEP-8 or being highly specialized, or etc, and proposals to bring them more in line have received pushback over their potential for more harm than good (see [8] for an example) (which is completely valid).
[1] https://mail.python.org/pipermail/python-ideas/2015-March/032545.html [2] https://mail.python.org/pipermail/python-ideas/2015-March/032556.html [3] https://www.youtube.com/watch?v=x-kB2o8sd5c [4] https://www.youtube.com/watch?v=OSGv2VnC0go [5] https://github.com/jcrocholl/pep8/blob/master/pep8.py#L68 [6] http://pep8.readthedocs.org/en/latest/intro.html#error-codes [7] https://github.com/jcrocholl/pep8/pull/313 [8] http://bugs.python.org/issue23061#msg233065
~ Ian Lee
On Mar 17, 2015, at 11:33 PM, Ian Lee ianlee1521@gmail.com wrote:
- There are a number of checks that are disabled in pep8 by default, due to their being somewhat controversial for many users [5] which you can read about what each of them are for in the docs [6] if you're interested.
I don't know that the rules themselves are necessarily controversial, so much as the way the checks are implemented.
I enabled E226 to see what it does (just because it sounded like the easiest one to test without reading further).
It flags the "Yes" examples from the PEP ("c = (a+b) * (a-b)") as an error, and passes the corresponding "No" examples ("c = (a + b) * (a - b)"). No wonder it's controversial.
What's going on? The rule it enforces is "always put whitespace around arithmetic operators", but the rule in the PEP is "If operators with different priorities are used, consider adding whitespace around the operators with the lowest priority(ies)."
But how exactly can an automated checker "consider" doing something? Clearly always doing it is not what's intended. Even besides the examples, in a document that starts off by telling you it's only a guideline and should not be followed slavishly or rigidly, any part that goes out of its way to say "consider" and follow with "use your own judgment" must have a reason to do so.
So, your judgment can tell you that the No example has too much whitespace. But the pep8 code can't.* And this is, presumably, why the E226 code has no problem with it, which in turn is presumably why users have a problem with the E226 code.
So, I don't think the fact that some of the checks are disabled by default necessarily means there's any dissonance between PEP8 and the Python community, it just means there are things in PEP8 that, though worth following, are hard to codify as rigidly checkable rules.
* Maybe "can't" is a bit strong. But consider: Would your judgment be the same if the variables had longer names? If this were one line of a complicated multi-line expression? Even if you knew the rules that provided the answers to those questions, would you want to code them and turn pep8 into a massive 80s-style expert system?
* Andrew Barnert abarnert@yahoo.com.dmarc.invalid [2015-03-18 00:18:02 -0700]:
On Mar 17, 2015, at 11:33 PM, Ian Lee ianlee1521@gmail.com wrote:
- There are a number of checks that are disabled in pep8 by default, due to their being somewhat controversial for many users [5] which you can read about what each of them are for in the docs [6] if you're interested.
I don't know that the rules themselves are necessarily controversial, so much as the way the checks are implemented.
I enabled E226 to see what it does (just because it sounded like the easiest one to test without reading further).
It flags the "Yes" examples from the PEP ("c = (a+b) * (a-b)") as an error, and passes the corresponding "No" examples ("c = (a + b) * (a - b)"). No wonder it's controversial.
What's going on? The rule it enforces is "always put whitespace around arithmetic operators", but the rule in the PEP is "If operators with different priorities are used, consider adding whitespace around the operators with the lowest priority(ies)."
That was an addition made "recently" to pep8: https://hg.python.org/peps/diff/37af28ad2972/pep-0008.txt
I guess pep8 adopted by disabling that check by default, rather than completely removing it.
Florian
On Mar 18, 2015, at 12:30 AM, Florian Bruhin me@the-compiler.org wrote:
- Andrew Barnert abarnert@yahoo.com.dmarc.invalid [2015-03-18 00:18:02 -0700]:
On Mar 17, 2015, at 11:33 PM, Ian Lee ianlee1521@gmail.com wrote:
- There are a number of checks that are disabled in pep8 by default, due to their being somewhat controversial for many users [5] which you can read about what each of them are for in the docs [6] if you're interested.
I don't know that the rules themselves are necessarily controversial, so much as the way the checks are implemented.
I enabled E226 to see what it does (just because it sounded like the easiest one to test without reading further).
It flags the "Yes" examples from the PEP ("c = (a+b) * (a-b)") as an error, and passes the corresponding "No" examples ("c = (a + b) * (a - b)"). No wonder it's controversial.
What's going on? The rule it enforces is "always put whitespace around arithmetic operators", but the rule in the PEP is "If operators with different priorities are used, consider adding whitespace around the operators with the lowest priority(ies)."
That was an addition made "recently" to pep8: https://hg.python.org/peps/diff/37af28ad2972/pep-0008.txt
I guess pep8 adopted by disabling that check by default, rather than completely removing it.
So PEP 8 evolved to match changing community standards, maybe even in part because of community experience with the pep8 tool, and the tool adapted to those changes... So what needs to change here?
(If Ian was arguing that pep8, autopep8, etc. should remain outside the stdlib so they can continue to adapt at a reasonable pace, then I think I agree, but I think he was suggesting something different; I'll go re-read the post, and apologies in advance if I'm wrong.)
On 18.03.2015 07:33, Ian Lee wrote:
tl;dr -- How should style guides evolve?
So this is a post inspired largely by a thread that popped up today [1], and specifically Alex's message [2]. I didn't want to derail that conversation (specifically dealing with style checking / correcting as a part of the standard library), but I did want to start a separate thread for an idea that's been rattling around in my brain for a while now. (Disclaimer, I am the current lead maintainer of the pep8 package, so part of this comes from my work there.)
Namely, how should style guides, and here I'm particularly looking at PEP-8, evolve?
By revisiting them every now and them :-)
I think that people sometimes miss the "guide" aspect of PEP 8.
PEP 8 is a guideline for people to follow which results in readable code. It's not a the only such guideline. Many companies have their own which usually build on PEP 8 and then add some extra rules or modify PEP 8 rules.
Whether or not to use a tool enforcing a guideline like PEP 8 is really up to the user or the programming context.
I'm -1 on having a go like feature in Python which mandates one particular style, but absolutely nothing against tools applying a formatting specification to some Python code on demand :-)
On Mar 18, 2015, at 09:58 AM, M.-A. Lemburg wrote:
PEP 8 is a guideline for people to follow which results in readable code. It's not a the only such guideline. Many companies have their own which usually build on PEP 8 and then add some extra rules or modify PEP 8 rules.
Exactly. Also PEP 8 is deliberately noncommittal about certain style points. It shouldn't dot every t and cross every i <wink>.
Besides, PEP 8 was originally - and as its introduction still states - intended for the coding conventions of the standard library, where consistency is as important as it is lacking in practice. ;) You're supposed to define the coding standards for your own projects, and it's fine to include PEP 8 by reference. That's what we do for example with GNU Mailman (although it needs an update).
Cheers, -Barry
-
Andrew Barnert -
Barry Warsaw -
Florian Bruhin -
Ian Lee -
M.-A. Lemburg