Hi All, Apologies if this is considered off topic, but I'm keen to get the "language designers" point of view and short of emailing Barry, Guido and Nick directly, this seemed like the best place. I'm having a tough time persuading some people of the benefits of pep8, particularly when it comes to applying to an existing large code base. The biggest sticking point is naming, particularly as it's the one thing that can't necessarily be changed module by module. What were the compelling reasons to go from mixedCase to underscore_separated? What's considered the best approach for migrating from the former to the latter? A couple of others that have raised some consternation; what are the technical reasons for this pattern being bad: if len(seq) if not len(seq) ...or, for me, the rather ugly: if 0 != len(seq) Likewise, these: if greeting == True: if greeting is True: Please don't misunderstand me: I dislike the above intensely, but it's an emotional response based on 10-15 years of doing things the other way. I'm interested in arguments that don't include things like "it's pythonic" (which some people consider a derogatory term ;-)), or "just because", I trust that the stuff in pep8 was done with specific reasoning in mind, but I'm feeling rather useless at giving that reasoning and I'm hoping you can help :-) cheers, Chris
I doubt that it was the original motivation, but there have been evidence of late suggesting that snake-case is in fact _better_ than CamelCase. See for instance http://www.cs.kent.edu/~jmaletic/papers/ICPC2010-CamelCaseUnderScoreClouds.p... Science! K
On Thu, Apr 24, 2014 at 2:18 AM, Chris Withers <chris@simplistix.co.uk> wrote:
I never recall Python "going from" camelCase to separate_words. The descriptions of best practice you see in the PEP were always that way, as I recall. If you have a code base that does it some other way, I would leave it be. The primary hunk of code I work with is full of Boost.Python-generated bindings for C++ libraries, so leaks C++ naming style out of all its pores. A lot of the other pure Python code in this code base was written by people who were mostly C++ programmers, and didn't know PEP 8 from a hole in the ground. Consequently, the whole thing is riddled with all sorts of non-pep8-ness. I used to want to change everything, but just let that sleeping dog lie. I have better things to do with my life. New stuff I write tends to be much more pep8-ish. Skip
On Thu, Apr 24, 2014 at 10:18 AM, Chris Withers <chris@simplistix.co.uk> wrote:
As far as I know that reason for these examples being frowned upon is that they are needlessly redundant. This is not just a matter of minimalism or style; it's a matter of readability. If you're relying on the "len()" call to fail if "seq" isn't a container (for example, if it's None), the code for that should be separate and more explicit. Regarding "if something == True", that's only the same as "if greeting" if greeting is assumed to be a boolean value. If so, it is better (for readability) to use a descriptive variable name: "if should_greet:". Otherwise (e.g. if greeting could also be None) it is reasonable to check if it is equal to a specific value (with a short comment explaining this point!). Also, there's no end to how much comparison to True one can do: if (greeting == True) == True if ((greeting == True) == True) == True Considering that, IMO it makes sense to just avoid such comparisons altogether. - Tal Einat
On Thu, Apr 24, 2014 at 01:57:38PM +0100, Tim Golden wrote:
Not really ironic, since not all redundancy is needless. Useful redundancy: an emergency backup chute; if your main parachute fails to release, you have a backup. RAID. Backups in general. There's a lot of redundancy in human language in general, which makes it possible to understand speech even in noisy enviroments. Needless redundancy: a double-headed spoon, in case the first bowl disintegrates in your soup, just turn the spoon around and use the spare. Or the abuse of Hungarian Notation perpetrated by the Windows development team. http://www.joelonsoftware.com/articles/Wrong.html One mild but legitimate criticism of Python's significant indentation feature is that it loses some useful redundancy: you can reconstruct the indentation from the braces, or the braces from the indentation, but if you only have one, and it gets lost in transmission, you're screwed. (The lesson of this, as far as I am concerned, is "Don't transmit source code through noisy channels that delete parts of your code.") -- Steven
On Apr 24, 2014, at 08:18 AM, Chris Withers wrote:
I'm having a tough time persuading some people of the benefits of pep8, particularly when it comes to applying to an existing large code base.
First of all, the purposes of PEP 8 is not to impose mandates of style on your colleagues. :) Two important quotes are useful to keep in mind: Introduction This document gives coding conventions for the Python code comprising the *standard library* in the main Python distribution. (emphasis added) A Foolish Consistency is the Hobgoblin of Little Minds A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important. [...] Some other good reasons to ignore a particular guideline: To be consistent with surrounding code that also breaks it (maybe for historic reasons) -- although this is also an opportunity to clean up someone else's mess (in true XP style). While I personally think PEP 8 is good enough to adopt for my own projects, and I encourage other projects to also adopt the guidelines where appropriate, doing so is *not* always appropriate in existing source code outside the standard library (and sometimes even within the stdlib, e.g. unittest).
If your existing code base is already mixedCase, then there's no compelling reason for a wholesale transition, IMO. I work with plenty of existing mixedCase code and it's much more jarring to see a mix of styles than it is to see consistent mixedCase naming. OTOH, some projects do choose to adopt PEP 8 style names over time, and they have to manage all the expected API guarantees involved in that. I will say this: the original preference for underscore_names in PEP 8 was spurred by user studies some of our early non-native English speaking users conducted many years ago. We learned that it was more difficult for many of them to parse mixedCase names than underscore_names. I'm afraid I probably no longer have references to those studies, but the difference was pronounced, IIRC, and I think it's easy to see why. Underscores can be scanned by the eye as spaces, while I'd hypothesize that the brain has to do more work to read mixedCase names.
Well, I'd write that as `len(seq) != 0` but still, I get your point. The rationale for this is that generic truthiness is a wider check then an explicit value check, and EIBTI. This really comes down to the difference between if not thing: vs if thing != other: In the first case, any falsey value makes it through, while in the second case, you're being more explicit about what you think the value of `thing` can be. So when semantically `thing` can be 0 or None or '', then the first test is preferred. When `thing` can't just be any truthy or falsey value, then a more explicit check is preferred, otherwise some unexpected falsey value might slip through. It might seem less applicable to the len(seq) case, but I'd offer that that's just an application of a more general principle.
This one is based on the preference for identity checks when singletons are involved, rather than equality tests. Being composed of English words, the latter is also more readable. It's the same reason why you would do identity checks against None or enum values.
I hope those explanations give you the basis for why the choices were made. They aren't arbitrary, although folks can and do disagree. It's much more important that your project comes up with its own guidelines and applies them self-consistently. For example, I have my own small set of refinements on top of PEP 8. I'm not providing a link because they're a bit out of date w.r.t. Python 3. ;) Cheers, -Barry
On Thu, Apr 24, 2014 at 7:11 AM, Skip Montanaro <skip@pobox.com> wrote:
I'm sorry, I have no recollection of such studies. (ABC used case differently anyway, so camelcase wasn't possible there -- and neither were underscores). Barry maybe referring to a more informal survey of feedback from Python users at the time. But I have no recollection of that either. -- --Guido van Rossum (python.org/~guido)
On 2014-04-24 14:59, Barry Warsaw wrote:
A more recent set of studies show some mixedResults (ha ha). On a low-level reading task, the studies agree with yours in that mixedCase takes more time and effort; however, it appears to improve accuracy as well. On a higher-level comprehension task, mixedCase took less or the same time and still improved accuracy. Experienced programmers don't see too much of a difference either way, but inexperienced programmers see a more marked benefit to mixedCase. http://www.cs.loyola.edu/~binkley/papers/tr-loy110720.pdf That said, I can't vouch for the experiments or the analysis, and it isn't really germane to Chris' historical question. I mention it only because I had just run across this paper last night, so it was fresh in my mind when you mentioned studies on the subject. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
One added note:
There is more to it that that -- == can be overridden for a particular class. So doing: X == None Could yield surprising results if __eq__ has been defined for the class X is bound to at the moment. Numpy arrays are a common case for me. As None is often used to mean undefined, X could be any type. Granted, in your code, you likely know what type(s) X is likely to be, but it's a good habit to get in to. -Chris
On Thu, Apr 24, 2014 at 4:59 PM, Barry Warsaw <barry@python.org> wrote:
I speak two languages as mother tongues - English and Hebrew. Hebrew has no capital letters (and is also right-to-left) and is the spoken and written language in the parts of Israel where I've lived most of my life. Perhaps because of this, I do find that capital letters don't quite "jump out" for me and therefore I find mixedCase and CamelCase harder to grok at a quick glance than under_score_names. - Tal
On Apr 24, 2014, at 06:51 PM, Tal Einat wrote:
I was musing at Pycon with others about how Go would handle identifiers in languages that don't have capital letters, such as Hebrew, given the fact that they use the case of the first letter to control identifier visibility. Their FAQ essentially punts on the issue (start your identifier with a letter that can be capitalized, e.g. X日本語) but says that this feature will likely stay. I guess it's Go's flavor of Python's whitespace rule. :) -Barry
On Thu, Apr 24, 2014 at 11:59 PM, Barry Warsaw <barry@python.org> wrote:
Underscores also play much more nicely with initialisms. How would you spell a function named "Add HTTP Header"? add_HTTP_header add_http_header addHTTPHeader addHttpHeader Four options to choose from. The first two clearly separate the initialism from the other words; take your pick whether you want it uppercased or not, because it's separated either way. In mixedCase, the first one merges the H of Header in with HTTP; with something less well known, that can be a nasty readability problem. The second one is probably more readable, but looks weird. Or, here's another one: converting one thing into another, where both are named by their initials: convert_XML_to_JSON convert_xml_to_json convertXMLToJSON convertXmlToJson Same four options. Which is the more readable? ChrisA
There's been a bit of serious study on this. The results are still open to interpretation, though ;-) Here's a nice summary: http://whathecode.wordpress.com/2011/02/10/camelcase-vs-underscores-scientif... of-course-dashes-are-most-natural-ly y'rs - tim On Thu, Apr 24, 2014 at 11:25 AM, Chris Angelico <rosuav@gmail.com> wrote:
[Tim]
[Terry Reedy]
The linked poll is almost evenly split, 52% to 48% for camel case with over 2000 votes each.
There are two polls in the post. You're referring to the first, which the author asked viewers to fill out before reading any of the "evidence". There's another poll at the end, which the author asked viewers to fill out after reading the whole post. In that poll, preference changed (56% to 44% in favor of underscore). A followup post summarized later research, confirming the earlier result that CamelCase'd names are harder to read (as measured by eye tracking studies): http://whathecode.wordpress.com/2013/02/16/camelcase-vs-underscores-revisite... but-all-obvious-a-priori-to-the-most-casual-observer<wink>-ly y'rs - tim
On Thu, Apr 24, 2014 at 11:36:03AM -0500, Tim Peters wrote:
To summarize the key points of the two papers referenced in this thread: Blinky 2009: Participants were trained in camelCase. camelCase was 13.5% slower, 51.5% more accurate on an identifying task. Sharif 2010: Participants were trained in underscores. Same accuracy, camelCase was 20% slower. It seems like, generalizing, camelCase is slower and more accurate, while training affects both speed and accuracy. But, really, there is no compelling scientific argument here. It really boils down to CONSISTENCY: 1) If the existing code uses one or the other, follow the original code to preserve CONSISTENCY. 2) If you're starting a new project, follow PEP8 (or the standards for the language you're using) to preserve CONSISTENCY.
On Fri, Apr 25, 2014 at 11:40 AM, Allen Li <cyberdupo56@gmail.com> wrote:
2) If you're starting a new project, follow PEP8 (or the standards for the language you're using) to preserve CONSISTENCY.
Don't forget that PEP 8 is not the standard for the Python language, only the Python stdlib. Particularly, there's no strong reason to follow some of its lesser advices (eg spaces rather than tabs, the exact maximum line length) for new projects; if all your developers have good quality screens, there's no point wrapping all your code to 79 just because the Python standard library is wrapped to 79. That particular example is touched on in the PEP itself (suggesting 20 more characters); you could easily set a maximum of 89, 99, or 159 characters if it makes sense for your project. Consistency with the standard library in names is slightly more useful, but the standard library isn't perfectly consistent itself (eg not all class names start with a capital), and if you're spending too much time arguing about style instead of getting code written, your style guide isn't doing its job :) ChrisA
On 25/04/2014 04:03, Barry Warsaw wrote:
Right, so for me this means even in a private code base, there are big benefits to using PEP 8; everything looks the same, whether it's a third party library, python core or your own code... Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
On 25/04/2014 13:09, Chris Withers wrote:
I essentially had this conversation via my blog a couple of years ago: http://ramblings.timgolden.me.uk/2012/03/27/pep8-or-not/ http://ramblings.timgolden.me.uk/2012/03/29/more-on-pep8/ http://ramblings.timgolden.me.uk/2012/04/09/pep8-it-is-then/ and was quite surprised at the strength of feeling evoked. As you can even tell from the titles of the posts, I ended up by accepting that, even though I'm at liberty to apply my own format to my own code, it would be more of a community-friendly idea to use [near-enough] PEP8 regardless. As you can also see from the comments throughout, YMMV. :) TJG
Chris Withers writes:
On 25/04/2014 04:03, Barry Warsaw wrote:
Indeed. But channeling the FLUFL here, I would say that in your situation where people have already developed a large code base that apparently isn't shared much (if at all) outside the organization, they've already paid the price of nonconformity for the existing code base. If there's a formal standard, and you don't expect the "insiders only" policy to change soon (assuming it actually exists), I don't see why you would push for a change to PEP 8 at all. If you *don't* have a formal standard and existing code is a mixture of styles, I'd be very tempted to say "PEP 8 for new modules" (even if some of the mix is consistent -- for example all the ex-C++ programmers like CamelCase). Ditto if you're going to be developing modules to publish as OSS. And from *outside* of your organization, it's a no-brainer. PEP 8 is what Python itself and most 3rd party OSS modules use. Getting your people to use PEP 8 will make it a lot easier for them to learn to read Python core and stdlib code, and once they start reading --- why, the obvious next step is *contributing*. Yay! ;-)
On Apr 25, 2014, at 11:06 PM, Stephen J. Turnbull wrote:
And if you do deviate from PEP 8, I think it's quite helpful to publish a style guide outlining the deviations. It helps others contribute to your project. Of course, the first line of that style guide should be: `PEP 8`_ is the basis for this style guide so its recommendations should be followed except for the differences outlined here. :) cheers, -Barry
On 25 April 2014 10:36, Barry Warsaw <barry@python.org> wrote:
And if you're going to publish a tool to enforce your *personal* style guide and include your own custom rules that the "this is OK" examples in PEP 8 fail to satisfy, don't call it "pep8". Especially don't do that if you're then going to ignore a core developer that calls you on misappropriating python-dev's authority :( Regards, Nick. P.S. https://github.com/jcrocholl/pep8/issues/256 -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
2014-04-25 18:10 GMT+02:00 Nick Coghlan <ncoghlan@gmail.com>:
I am the current maintainer of this 'pep8' tool which was mentionned in a previous message. The tool was first published in 2006 by its original author. I take the feedbacks of the users in consideration, as much as I can. When something is unambiguously identified as a bug, I try to merge a patch in a timely manner. If it is an enhancement or a change of behavior, it is not in the priority list, of course. Two cases where signaled in the issue #256 last month, where the tool is arguably not compliant with some of the current conventions of the PEP. I've highlighted the reasons behind these checkers in the issue tracker directly. I disagree that they are in direct opposition with the PEP 8 coding conventions, though. The first concern is about 4 spaces indentation for continuation lines. For this point, the text of the PEP says "Use 4 spaces per indentation level", which lets room for interpretation (like some other parts of the PEP). However I changed some stuff in v1.5 to better isolate this case, so the user can add E121 safely to the ignore list: https://github.com/jcrocholl/pep8/blob/master/CHANGES.txt#L96-L105 The second concern is about compound statements, which are "generally discouraged" in the words of the PEP. Technically, there's no obvious way to implement "generally discouraged" in code. The compromise is to disable the check E701 and "use your own judgment" instead, if you feel it does not match you project's style guide. By the way, the example reported in #256 was only added last year to the PEP: def f(x): return 2*x And if we look closer to the PEP 8 history for the last two years (since March 2012), there were lots of changes and I've already updated the tool to catch up with some of them. However the tool has a large base of users, and I try to preserve some stability instead of removing features every time someone has an objection. In such case, what I recommend to the users is to configure the tool to ignore the checks which conflict with their own habits or conventions. I wrote some words in the documentation, one year ago, to explain what is the purpose of the tool and its limitations. There's no claim of any endorsement implicit or explicit by the PSF, the PSU or any other python developer :-) http://pep8.readthedocs.org/en/latest/intro.html#disclaimer I'm sorry if you felt that my previous answer was an offense to some python-dev authority, this is not intentional. Kind regards, -- Florent
On 04/25/2014 12:45 PM, Florent wrote:
The problem is that you've named it pep8. To me, that means I can run it and get PEP 8 results. If I have to add a manual configuration to get actual PEP 8 semantics, it's a buggy tool. For a similar example, I am the author/maintainer of enum34, which purports to be the backport of Python's 3.4 enum class. While I could go and make changes to it to better match my style, or even the styles of other users, calling it enum34 after that would be misleading as some one couldn't then switch from using enum34 in Python 3.2 to using the default enum in Python 3.4. If you had extra switches to turn on extra behavior, that would be fine. Leaving it as it is, and calling it something else would be fine. But as it stands now, with the name of pep8 and the behavior of failing on the PEP 8 document... well, that's false advertising. -- ~Ethan~
On 04/25/2014 01:55 PM, Ethan Furman wrote:
I think this fuss is unreasonable and unwarranted. I'd like to thank Florent for taking the time to maintain an extremely-useful tool that makes it feasible to keep to a consistent PEP 8 style throughout a large codebase with many contributors, and I think he should have the leeway as maintainer to make the necessary judgment calls about precisely which PEP 8 recommendations are reported precisely how by the tool, given that: - we aren't talking about real variance from the spirit or recommendations of PEP 8 (though you wouldn't know it from some of the rhetoric here about "personal preferences") - the tool makes it very easy to turn off whichever errors you don't prefer to enforce. - PEP 8 changes regularly (as Florent noted, the offending code example was only added recently), and there is value in the automated tool maintaining some stability for its users. Personally, I would much rather see pep8.py err on the side of being too strict with PEP 8's recommendations than too loose. Again, it's not hard to turn off the ones you don't want. If python-dev wants to control the precise behavior of pep8.py, bring it into the standard library and adopt maintenance of it. Otherwise, please give Florent some grace. Carl
On Apr 25, 2014, at 5:52 PM, Carl Meyer <carl@oddbird.net> wrote:
Carl’s post mirrors my own thoughts and it’s said much better than I could have. pep8.py doesn’t violate PEP8, it just takes a stricter view of it. ----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On 25 April 2014 18:26, Donald Stufft <donald@stufft.io> wrote:
In other words, it adds rules that have not been discussed on python-dev, and effectively claims that those rules are part of PEP 8 when they're not. Note that my problem is *specifically* with errors, and especially with errors that are on by default. Even with the name "pep8", warnings and below are clearly at the discretion of the tool authors and maintainers, and while "off-by-default" errors strike me as nonsensical (why not just make them warnings instead?), I also don't have a problem with adding more of them. However, keeping E121 (which requires all indentation of continued lines in expressions to also be a multiple of 4, rather than only semantically significant indentations) and E701 (which completely disallows the use of single line compound statements, even through the PEP text only discourages them) as errors rather than warnings is apparently more important than my wholehearted endorsement of the tool as a co-author of PEP 8. So be it - but while that is the case, pep8 is *not* a PEP 8 linter, it remains "PEP 8 plus extra rules python-dev has never discussed". Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
2014-04-26 0:46 GMT+02:00 Nick Coghlan <ncoghlan@gmail.com>:
You're a co-author of PEP 8 since less than a year. I'm the maintainer of the pep8 tool since 2010. You should probably read the LICENSE file which is shipped with the pep8 too, and the disclaimer that I've posted previously. Never I engage the responsibility of the authors of the PEP 8 document, and I don't give any guarantee of being a *strict* PEP 8 compliance tool. However, you should notice that your ticket in the tracker is opened for 2 months only, and I did not flagged it as being resolved. As I've stated in my previous mail, I give priority to bugs over other requests. And even if you think it is a critical bug for yourself, it did not appear like that for the thousands of people which used the library for the last few years. But if you read the documentation carefully, you can see that I've already excluded some checks from the default behavior in the previous releases, when there was an argument which was backed by the PEP 8 itself: "In the default configuration, the checks E123, E133, E226, E241 and E242 are ignored because they are not rules unanimously accepted, and PEP 8 does not enforce them." http://pep8.readthedocs.org/en/latest/intro.html#error-codes The question stay opened for issue #256 and codes E121 and E701. As I said before, they are not against PEP 8, they interpret some words. If you're nitpicking, you can probably reject half the checks of the pep8 tool with similar allegations.
I *want* to be able to recommend this tool universally. But at the moment, I cannot, as its name is a lie: it enforces rules I don't personally agree with.
Maybe I prefer you don't recommend it in the PEP 8 documentation if it means I'll be tied to your "personal preferences" and that I'll be forced to patch it every now and then when you change a line, or a punctuation in a PEP 8 example. At the end, I find you're a bit rude when you come to this project which is not endorsed by the PSF or any Python-Dev related entity and you say "this project is wrong, because the developer did not obey to me when I order to remove that feature". You're more sympathetic and less in a hurry when it comes to some languishing bug on b.p.o :-) If you're so impatient, let's fork it and put in in cpython/Tools/ I would not fight against it. Sincerely, -- Florent
On Apr 25, 2014, at 7:56 PM, Florent <florent.xicluna@gmail.com> wrote:
I agree that I’ve never taken the name to mean that you’re claiming any sort of endorsement. There are a *vast* number of projects that implement something that was defined somewhere else and I don’t think any reasonable person can assume that all of those tools are endorsed by the authors of what they are implementing.
----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On Fri, Apr 25, 2014 at 08:13:35PM -0400, Donald Stufft wrote:
I think that is wrong. "Endorsed" is the wrong word -- what's important is that if package PEP8 "checks for PEP 8 compliance", then if package PEP8 checks for foo, then people assume that foo-checking is specified by PEP 8 -- whether it does or not. If something claims to be "JSON", say, then most people would expect that by default it would implement the JSON standard rather than some tweaked version of almost JSON. If their JSON library fails to match the standard, a significant number of people will assume that the library's non-standard version *is* the standard. It may even become the de-facto standard, regardless of what the standard actually says, and so introduce ambiguity where there was none. E.g. consider browser's treatment of ISO-8859-1 as Windows-1252. People and corporations often take this sort of stuff really seriously, and I'm not surprised that Nick feels as strongly as he does. I would too. Try releasing a package using the name "iPhone" without Apple's approval: https://developer.apple.com/softwarelicensing/index.php In this case, I too would have assumed that a package calling itself "PEP8" checks for compliance with PEP 8, and that any differences between PEP 8 and the package is a bug in the package. Providing the ability to turn on or off checks, or make them more or less strict, is okay, but I would expect that by default it should check for PEP 8 compliance, exactly PEP 8 compliance, and nothing but PEP 8 compliance. -- Steven
On 25 April 2014 19:56, Florent <florent.xicluna@gmail.com> wrote:
I apologise for my impatience. As I stated in that issue, I really *want* to be able to uncritically endorse pep8 for use on new Python projects, as while I like pylint personally, I think it's too complicated (and noisy by default) to recommend its use outside large multi-developer projects where taking the time to set up a custom config file is likely to pay off. Hence it's frustrating to me that I can't currently recommend pep8 for this use case, as the default behaviour includes rules I disagree with (in particular, the ones that the examples in PEP 8 itself fail). I believe the combination of the implied endorsement from the name of the tool and an explicit endorsement from me saying "use this on your projects" would imply that I agree with *all* the default behaviour, and that simply isn't the case (E121 in particular is outright wrong, since it violates the approach of aligning indented lines with an opening parenthesis). It seemed simple enough to me to say "yes, that makes sense, we can make those warnings eventually, but it's not a high priority to do so". That would put it back on me to craft a pull request to make the change, and would be an entirely appropriate response when I'm asking other people to do extra work. That hasn't been my impression of the response I received to date though - my impression of the response has been "we don't care about your feelings". Defending PEP 8 against people who think it's overly prescriptive is irritating enough, without having to also figure out whether people are actually complaining about the PEP or about a tool I didn't help write :( Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 25 April 2014 21:29, Nick Coghlan <ncoghlan@gmail.com> wrote:
Note that I've now resumed this discussion on the pep8 issue tracker (including splitting out a separate RFE specifically relating to the new'ish guideline for handling of single line function definitions). My apologies to Florent specifically, and the list in general, for letting frustrations with unrelated issues boil over into impatience and unconstructive criticism of a fellow open source contributor's efforts. Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
I think the tool's name is unfortunate. The first time I heard about it I was having an in-person discussion with a developer who (I thought) said that "PEP 8" was okay with his code (which I knew couldn't be the case) but in fact he meant to say that (some configuration of) "pep8" didn't mind it. This took some time to sort out and it would have avoided if the tool had had a better name. That said I think it's a great tool. On Fri, Apr 25, 2014 at 4:20 PM, Ethan Furman <ethan@stoneleaf.us> wrote:
-- --Guido van Rossum (python.org/~guido)
2014-04-26 1:46 GMT+02:00 Guido van Rossum <guido@python.org>:
Thank you, Actually I did not choose the name. I just took over the project 4 years ago by accident because I had some pull requests languishing and the author of the project was no longer interested in it. I agree that the name is a source of confusion in some cases. I've mitigated some conflicts with PEP 8 by incitating contributors to write "flake8" extensions instead of pushing more features into "pep8" itself, and also I tried to define a default configuration which is "good enough" to support the PEP 8 recommendations. -- Florent
On Apr 25, 2014, at 7:20 PM, Ethan Furman <ethan@stoneleaf.us> wrote:
Not really, any code that passes the pep8.py check is perfectly valid in the eyes of PEP8, if a check was implemented to say, require camelCase method names, then that would be a violation of a check. Being stricter is not a violation, it’s being stricter. ----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On 04/25/2014 05:42 PM, Donald Stufft wrote:
Then it should be called stricterThanPep8. ;) I think we're going to have to agree to disagree on this point. A tool that implements PEP 8 [1], but tells me that something PEP 8 allows is an error -- well, that's not PEP 8 then, is it? At any rate, this part of the thread is pretty off-topic, so this is my last post about it. -- ~Ethan~ [1] Yes, I checked the site for pep8, and saw the escape clause of "some of the style conventions" -- the problem is the cognitive dissonance between the name of the tool and the actions of the tool.
On Fri, Apr 25, 2014 at 08:42:02PM -0400, Donald Stufft wrote:
Suppose that some package claiming to check for PEP 8 compliance decided to flag variable names like "foo" and "bar" as errors. Perhaps it was inspired by Tim Peters: Indeed, when I design my killer language, the identifiers "foo" and "bar" will be reserved words, never used, and not even mentioned in the reference manual. Any program using one will simply dump core without comment. Multitudes will rejoice. -- Tim Peters, 29 Apr 1998 Or perhaps it decides that one should never, ever have more than a single dot in a row, a treat that as an error: obj.method() # okay obj.method().attribute # Law Of Demeter violation This hypothetical checker is stricter than PEP 8, in that it allows nothing that PEP 8 forbids. But it also forbids things which are allowed by PEP 8, which is a false negative error: things which should be allowed (according to PEP 8) are forbidden by the checker. (The other kind of error is a false positive, where things which are forbidden by PEP 8 are wrongly allowed by the checker.) I stress that they're only errors if the checker is running in PEP 8 compatibility mode, where it is supposed to check for PEP 8 compliance. That's the crux of Nick's, and Ethan's, argument: with a name like "PEP8", it is reasonable to expect that by default the checker operates in PEP 8 compatibility mode. I agree with them. -- Steven
On 25 April 2014 17:52, Carl Meyer <carl@oddbird.net> wrote:
Yes we are. My name is on PEP 8 as one of the three co-authors, and my request to downgrade anything in the "pep8" tools that is not *explicitly* disallowed by the PEP to be a warning at most has been ignored. If you read the GitHub issue, you can see I *want* to be able to recommend this tool universally. But at the moment, I cannot, as its name is a lie: it enforces rules I don't personally agree with, yet claims to be based on a PEP I helped write. There is a way to get changes made to the common guidelines in PEP 8: you bring your case to python-dev and argue for the adoption of those rules in the standard library. If a tool doesn't claim to be speaking in my name, I don't care what rules it enforces. If a tool adds extra warnings, I also don't care. But "pep8" currently claims as errors code that is listed *in PEP 8 itself* as acceptable. I am *not* OK with that.
- the tool makes it very easy to turn off whichever errors you don't prefer to enforce.
This is about the default behaviour, and claiming as errors things that are explicitly listed in the PEP as OK.
No, this is exactly the *wrong* way to approach it. A tool laying claim to PEP 8's authority should err on the side of *not* enforcing rules that are not clearly rules - if more clarity is desired, then ask for clarity from python-dev.
Note that I don't complain about the default behaviour of pylint, pychecker, or any other linter tools. But by continuing to call the tool "pep8", Florent is claiming the endorsement of the PEP 8 authors and the consensus of python-dev for the tool's default behaviour (as noted above, this makes it personal for me, as I am a co-author of PEP 8). There is a very, very simple guideline that can be followed here: anything which is not clearly and unambiguously disallowed in the PEP itself should never be more than a warning in a tool that is called "pep8". Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 4/25/2014 5:52 PM, Carl Meyer wrote:
- we aren't talking about real variance from the spirit or recommendations of PEP 8
So the one example under discussion is: foo = long_function_name( var_one, var_two, var_three, var_four) and comes from http://legacy.python.org/dev/peps/pep-0008/#indentation Specifically the third example with a heading of "Optional". From my reading of the text, plus all the other examples around it, I would have assumed the 2 space indent was simply a typo and should have indeed been 4 spaces. If this is really meant to show that indents other than 4 spaces are allowed in this situation maybe verbiage to that effect could be added. Janzert
On Sun, Apr 27, 2014 at 9:40 AM, Barry Warsaw <barry@python.org> wrote:
wow! just looked at that part of the PEP again, and that is a LOT of options. Is it impossible to come to any consensus on this? And as it happens, my favorite is not in there, though as far as I can tell not forbidden: foo = long_function_name(var_one, var_two, var_three, var_four) That is, I find that if the argument list is too long for one line, then splitting it out to only one argument per line is much more readable to me. This becomes more important with default parameters: foo = long_function_name(var_one, var_two=a_value, var_three=some_other_value, var_four=(a, tuple, of, values) ) as with more information in each argument, it's a lot more clear where one starts and the other begins. And it provides a nice place for comments: foo = long_function_name(var_one, var_two=a_value, # because default doesn't frobnicate in this case var_three=some_other_value, var_four=(a, tuple, of, values) ) Anyway -- is there a point in trying to standardize this a bit more in PEP8, or has that battle long since been fought and conceded ? -Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
On 4/27/2014 3:34 PM, Chris Barker wrote:
One arg per line is definitely permitted either when lining up with the first arg on the first line or with hanging indents.
In a fixed-pitch font, you have too many spaces for lines after the first. One advantage of hanging indent is that all arg lines have the same indent and thus the args line up regardless of the font. Hanging indents also give more space for default or named args and comments. I would agree with having at least one example done with one arg per line. -- Terry Jan Reedy
On Sun, Apr 27, 2014 at 04:28:20PM -0400, Terry Reedy wrote:
Is it really necessary? I think that one-arg-per-line is an obvious variation of the existing example. If the only example given was one-arg-per-line, then the reader might wrongly assume that *only* one arg was allowed. But since the example shows more than one arg per line (two in the above example), I expect that people will read it as "some arbitrary number" rather than "exactly two". So I don't think there's any need to show yet another example, especially since it's just a variation on the existing examples. -- Steven
On Sun, Apr 27, 2014 at 6:34 PM, Steven D'Aprano <steve@pearwood.info>wrote:
not really -- a lot of folks learn more from following examples. If all teh examples are the same in some aspect, we'll tend to think that that's intentional, and that is at least the recommended method....
If the only example given was one-arg-per-line, then the reader might wrongly assume that *only* one arg was allowed.
indeed -- but maybe less clear but the the fact that none of the examples show one argument per line, the implication is that that is discouraged. very had to document a widely variable standard! -Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
2014-04-27 21:34 GMT+02:00 Chris Barker <chris.barker@noaa.gov>:
FWIW, the tool pep8 has introduced continuation line indentation checks in 2012, based on the PEP 8 recommendations which were active at this date, and doing few extrapolations on cases which were not directly covered by the document (pep8.py v1.2, issue #64). Then we had a lot of iterations with the users of the library, and we've added more flexibility to cover the various styles which were in the spirit of PEP 8, and which give some added value for code readability. The end result of this work can be seen in the test suite : * more than 300 lines of rejected indentations: https://github.com/jcrocholl/pep8/blob/master/testsuite/E12.py * and more than 600 lines of acceptable cases: https://github.com/jcrocholl/pep8/blob/master/testsuite/E12not.py I don't think that the PEP 8 document should go in so much details, though. However these examples might help to have pragmatic discussions about which rules we want to recommend. Do not hesitate to give feedback here, or on the issue tracker. There's also a code-quality mailing-list which covers a little more than pep8.py: https://mail.python.org/mailman/listinfo/code-quality -- Florent
On Apr 27, 2014, at 12:34 PM, Chris Barker wrote:
Wow, do you really indent those 42 columns? This actually is forbidden because you're not using "vertical alignment" when there is an argument on the first line. You would have to line up `var_two` right under `var_one` to be compliant.
That is, I find that if the argument list is too long for one line, then splitting it out to only one argument per line is much more readable to me.
Sure. The PEP outlines ways to do that.
The only thing I see wrong (from a PEP 8 standpoint) with your example, is that your arguments are indented too far to the right. But e.g. this would be fine: foo = long_function_name(var_one, var_two=a_value, var_three=some_other_value, var_four=(a, tuple, of, values) ) Cheers, -Barry
On Sun, Apr 27, 2014 at 1:40 PM, Barry Warsaw <barry@python.org> wrote:
No -- stupid variable-width font! I don't think anyone should write code with variable width fonts, and I'd rather not do email that way either, but gmail is making it tough these days.. Sorry for the added confusion. This actually is forbidden because you're not using "vertical alignment"
yeah -- that was the intent.... oh well.
not really -- it allows it: # Aligned with opening delimiter. foo = long_function_name(var_one, var_two, var_three, var_four) but all the examples have more than one variable per line...my point is that I think that should be discouraged. i.e. I think the above should be: # Aligned with opening delimiter. foo = long_function_name(var_one, var_two, var_three, var_four) (done with fixed-width font this time -- but it may not look right in your mail reader..) though I doubt there would consensus on requiring that -- but many of us learn more from examples than the specification, so maybe I'll submit a patch with an example like that. -Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
On Apr 28, 2014, at 11:12 AM, Chris Barker wrote:
Ouch. I'm sure it's gmail being "helpful" the way <http://wiki.list.org/x/2IA9> is similarly helpful.
Fortunately, my mail stack is sane. :)
I also very much doubt you'd get consensus on that as a requirement, and I would oppose the PEP taking a stand one way or the other. I'm not sure that the PEP needs an example to illustrate its acceptability. Cheers, -Barry
On 4/28/2014 2:12 PM, Chris Barker wrote:
I don't think anyone should write code with variable width fonts,
The problem is that fixed pitch does not work well for even a half-way complete unicode font and I don't know that there are any available. As far as I know, my Windows 7 only came with one unicode font that Idle finds. An advantage from my viewpoint is that spaces in this font are narrower that the average character, making multiple-of-4 indents and spaces around operators look pretty good to me. Given that PEP8 generally disallows adding spaces to make things line up, as in the following (a style I used to adhere to) a = 134543344 # big number bonge = 2 # short number it seems to me consistent to use the multiple-of-4 hanging indent style and not try to make things line up with an odd number of spaces in this one special case. -- Terry Jan Reedy
R. David Murray writes:
My unix fix-width terminal font handles most unicode (even a lot of non-bmp stuff...though I have no idea if it is readable :).
Oh, I bet you do. With a true fixed-width Unicode font, it's the *Latin-character* text that's painful, if not unreadable, because the aspect ratio needs to be close to 1.0 to handle ideographs, rather than the 0.5 or less common with Latin fonts. XTerm has an option to treat ideographs as double width. That does the trick (at least, I don't know any scripts that really really want an aspect ratio of 0.7 or 2.0).
On Mon, Apr 28, 2014 at 3:01 PM, Terry Reedy <tjreedy@udel.edu> wrote:
...
Is ironic that that looks like hell in my variable-width font email client? it seems to me consistent to use the multiple-of-4 hanging indent style and
not try to make things line up with an odd number of spaces in this one special case.
things aren't going to generally line up with a non-fixed width font no matter how you slice it, so I guess if you need to use one for your code, you're just stuck. But I suppose the "line up with the opening bracket" style isn't a good idea in that case. All the more reason not to standardize anymore that PEP 8 already does. -Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
On Mon, Apr 28, 2014 at 11:12 AM, Chris Barker wrote:
I don't have a problem with discouraging it, but it should not be flagged in pep8 (OK in pep8 --wink-wink-nudge-nudge-say-no-more-eh, though!) I usually do use the style you prefer, especially when the arguments want to be commented, but in many cases the arguments are semantically tuples. Eg, rect1 = paint_rectangle(point[1], point[0], # top, left textheight + 2 * padding, textwidth + 2 * padding, chartreuse)
On 4/27/2014 12:40 PM, Barry Warsaw wrote:
Given the commits to pep 8 after this, I take it you decided the example really is correct. I'm glad the clarifying sentence got added and comment in the example changed, that should make it clear that the 2 space indent isn't a typo. Janzert
Carl Meyer writes:
I would too. N.B. Nick's complaints are a sort of left-handed compliment, too.
Of course. But whether an example in the PEP passes or not is *not* a judgment call at all, IMO. Do you think that it is?
That parenthetical remark was unnecessary, and at least in my case, I understood very well that there is no "real" variance. I disagree with the implied requirements, however. A program *intended to test standard conformance* MUST (in the sense of RFC 2119) aspire to a higher standard than "in the spirit", don't you think? Anyway, that's what I think.
- the tool makes it very easy to turn off whichever errors you don't prefer to enforce.
This is precisely backward. *I* have no errors I prefer to enforce or not to enforce. I want "PEP 8 conformance", I don't want to think or make judgments about individual recommendations in PEP 8. I want to leave that up to the PEP 8 maintainers. I suspect that is a common use case.
Achieving "some" stability would not be difficult: version the error sets of the tool, and provide a switch to invoke specific versions. Each version could be dated, as well, to allow such stability without knowing the precise content of the version of PEP 8 or pep8.py. I personally would not use such a switch, however. I would either change my code to conform to current PEP 8, or not. ;-)
Again, for many users of the tool, that is precisely *not* why they want to use the tool. They want to delegate the decision of which rules to enforce to the PEP 8 authors. Since *you* have preferences, I repeat your words back to you: it's not hard to turn on the ones you want. (Or it needn't be.)
Note that what Nick is complaining about is not that pep8.py varies from PEP 8 -- that's inevitable -- but rather that the variation is not *acknowledged* as a bug. So python-dev (but you really mean Nick) doesn't want to control the precise behavior of pep8.py, as code. What Nick wants is for code *bearing the name* to conform to the PEP it was named for. For users who want PEP 8 conformance merely because it is the standard, that's exactly right. For those of you who want to pick and choose which rules to follow and how strictly, the name doesn't much matter, does it? I think that in naming we should consider the use cases of those who depend on the name to be meaningful as higher priority than those who don't, but make their own judgments anyway. Regards,
Florent writes:
Of course there is an implicit claim of endorsement: the name. Read the TeX license -- pretty much the only restriction is *you can't call it "TeX" or any variation including that trademark if it doesn't pass TRIP*. When Don Knuth cares that much that names denote conformance to standard, Nick is in really good company. I agree 100% with Nick: in a program named "pep8", the examples in PEP 8 should *all* pass in the sense of not being labelled errors. Of course if the PEP changes that doesn't mean you should withdraw or rename the program, or even that you are required to address the issue within any time span. But you should consider it a bug. That said, issuing *warnings* for discouraged-but-sometimes-allowed practices is a great idea. A stricter warnings-are-errors *mode* is a good idea, especially for automated checkers, but it should be configurable for different policies.
Disclaimers are for lawyers. Other people assume names mean what they say.
On Apr 26, 2014, at 12:31 AM, Stephen J. Turnbull <stephen@xemacs.org> wrote:
No there isn’t. For instance there are things on PyPI named after websites, like github, twitter, Facebook, etc. These things are not written by the companies behind those websites and are merely written to interface with those websites. Should we assume that those companies all endorse every single one of those projects simply because they chose a descriptive name for their project? The name indicates what it attempts to do, create a PEP8 linter, it makes no claim of endorsement by the authors of the PEP. You can say it’s confusing if it’s named pep8 but doesn’t actually make it “PEP8”, but claiming it’s endorsement isn’t correct.
Or required to address it at all if you don’t wish to. Since the issue is still open I assume that means that the author hasn’t decided what the correct remediation is yet.
----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
Donald Stufft writes:
OK, "endorse" is an inappropriate word to describe the problem inherent in naming a script "pep8.py" when the maintainers of PEP 8 say it doesn't implement the PEP. (Aside: In fact, in the cases you cite, you *may* assume implicit approval (or that the company in question has not yet discovered and complained about the usage), if not active endorsement. That is the implication of a "trade name", and I suspect many of the names you mention are registered trademarks as well.) However, be that as it may, your examples are irrelevant to the "spirit" of Nick's issue: PEP 8 is a standard, not a corporate reputation. Even if there is no implicit "endorsement", the maintainer of the program is using the name of the document, while he and others are arguing that it's up to him to decide about conforming to it. That is unfair to those users who do not care about the *content* of the standard, but only about the interoperability implied by a certification of conformance to the standard. And if you think "interoperability" is a strong word to apply to a style guide like PEP 8, maybe so -- but RFC 2119 is also just a style guide, and I would hope that you would not argue that misuse of terms defined in that document has no interoperability consequences.
In the case of a explicit decision to WONTFIX just because you don't want to, it becomes a deliberately sustained false-y, and renaming is the appropriate action. There is a huge namespace of strings starting with "py". Although some of the more attractive ones are already taken (pylint, pychecker, pyflakes), I'm sure there's plenty of room for creative naming left if 100% conformance to the standard is a non-goal for the maintainer of the script.
Since the issue is still open I assume that means that the author hasn’t decided what the correct remediation is yet.
In the case of a program intended to check conformance to a standard, it's not a matter for the script maintainer's decision. It's obvious what the specification of the correct remediation is. (The author may of course choose the implementation. Or, having tried implementation he may decide to acknowledge the bug but WONTFIX it as too difficult, but too difficult is obviously not true here.) It's always possible that the document is buggy (as suggested by Janzert the 2- or 3- space indentation may have been a typo), but again, that's for the authors of the standard, not of the script, to decide.
On Fri, Apr 25, 2014 at 1:28 PM, Guido van Rossum <guido@python.org> wrote:
Hmm. There've been a good few conversations on python-list where people have been reminded that PEP 8 is *not* all that important for other projects (beyond that it's an already-written style guide - when you're starting a C project you can argue style guides for weeks, but when you start a Python project you can just say "PEP 8" and skip the bikeshedding), which I took to mean that it's on par with any other style guide; but looking at it the other way, it can be seen as a strong recommendation. I'm just not sure about the word "standard" there - to me a standard is something that you MUST follow, like RFCs for internet protocols. But that's just a matter of terminology, I guess. ChrisA
On 25/04/2014 03:00, Chris Angelico wrote:
I'm not sure I agree with that. PEP 8 *is* the standard for the language, in that there isn't anything else. Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
Fortunately, Unicode provides us with the COMBINING LOW LINE character, combining the horizontal space-savings of camelCase with the underscore-indicates-separation properties of _. And it's a valid Python identifier. convertx̲mlt̲oj̲son On Thu, Apr 24, 2014 at 12:25 PM, Chris Angelico <rosuav@gmail.com> wrote:
I doubt that it was the original motivation, but there have been evidence of late suggesting that snake-case is in fact _better_ than CamelCase. See for instance http://www.cs.kent.edu/~jmaletic/papers/ICPC2010-CamelCaseUnderScoreClouds.p... Science! K
On Thu, Apr 24, 2014 at 2:18 AM, Chris Withers <chris@simplistix.co.uk> wrote:
I never recall Python "going from" camelCase to separate_words. The descriptions of best practice you see in the PEP were always that way, as I recall. If you have a code base that does it some other way, I would leave it be. The primary hunk of code I work with is full of Boost.Python-generated bindings for C++ libraries, so leaks C++ naming style out of all its pores. A lot of the other pure Python code in this code base was written by people who were mostly C++ programmers, and didn't know PEP 8 from a hole in the ground. Consequently, the whole thing is riddled with all sorts of non-pep8-ness. I used to want to change everything, but just let that sleeping dog lie. I have better things to do with my life. New stuff I write tends to be much more pep8-ish. Skip
On Thu, Apr 24, 2014 at 10:18 AM, Chris Withers <chris@simplistix.co.uk> wrote:
As far as I know that reason for these examples being frowned upon is that they are needlessly redundant. This is not just a matter of minimalism or style; it's a matter of readability. If you're relying on the "len()" call to fail if "seq" isn't a container (for example, if it's None), the code for that should be separate and more explicit. Regarding "if something == True", that's only the same as "if greeting" if greeting is assumed to be a boolean value. If so, it is better (for readability) to use a descriptive variable name: "if should_greet:". Otherwise (e.g. if greeting could also be None) it is reasonable to check if it is equal to a specific value (with a short comment explaining this point!). Also, there's no end to how much comparison to True one can do: if (greeting == True) == True if ((greeting == True) == True) == True Considering that, IMO it makes sense to just avoid such comparisons altogether. - Tal Einat
On Thu, Apr 24, 2014 at 01:57:38PM +0100, Tim Golden wrote:
Not really ironic, since not all redundancy is needless. Useful redundancy: an emergency backup chute; if your main parachute fails to release, you have a backup. RAID. Backups in general. There's a lot of redundancy in human language in general, which makes it possible to understand speech even in noisy enviroments. Needless redundancy: a double-headed spoon, in case the first bowl disintegrates in your soup, just turn the spoon around and use the spare. Or the abuse of Hungarian Notation perpetrated by the Windows development team. http://www.joelonsoftware.com/articles/Wrong.html One mild but legitimate criticism of Python's significant indentation feature is that it loses some useful redundancy: you can reconstruct the indentation from the braces, or the braces from the indentation, but if you only have one, and it gets lost in transmission, you're screwed. (The lesson of this, as far as I am concerned, is "Don't transmit source code through noisy channels that delete parts of your code.") -- Steven
On Apr 24, 2014, at 08:18 AM, Chris Withers wrote:
I'm having a tough time persuading some people of the benefits of pep8, particularly when it comes to applying to an existing large code base.
First of all, the purposes of PEP 8 is not to impose mandates of style on your colleagues. :) Two important quotes are useful to keep in mind: Introduction This document gives coding conventions for the Python code comprising the *standard library* in the main Python distribution. (emphasis added) A Foolish Consistency is the Hobgoblin of Little Minds A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important. [...] Some other good reasons to ignore a particular guideline: To be consistent with surrounding code that also breaks it (maybe for historic reasons) -- although this is also an opportunity to clean up someone else's mess (in true XP style). While I personally think PEP 8 is good enough to adopt for my own projects, and I encourage other projects to also adopt the guidelines where appropriate, doing so is *not* always appropriate in existing source code outside the standard library (and sometimes even within the stdlib, e.g. unittest).
If your existing code base is already mixedCase, then there's no compelling reason for a wholesale transition, IMO. I work with plenty of existing mixedCase code and it's much more jarring to see a mix of styles than it is to see consistent mixedCase naming. OTOH, some projects do choose to adopt PEP 8 style names over time, and they have to manage all the expected API guarantees involved in that. I will say this: the original preference for underscore_names in PEP 8 was spurred by user studies some of our early non-native English speaking users conducted many years ago. We learned that it was more difficult for many of them to parse mixedCase names than underscore_names. I'm afraid I probably no longer have references to those studies, but the difference was pronounced, IIRC, and I think it's easy to see why. Underscores can be scanned by the eye as spaces, while I'd hypothesize that the brain has to do more work to read mixedCase names.
Well, I'd write that as `len(seq) != 0` but still, I get your point. The rationale for this is that generic truthiness is a wider check then an explicit value check, and EIBTI. This really comes down to the difference between if not thing: vs if thing != other: In the first case, any falsey value makes it through, while in the second case, you're being more explicit about what you think the value of `thing` can be. So when semantically `thing` can be 0 or None or '', then the first test is preferred. When `thing` can't just be any truthy or falsey value, then a more explicit check is preferred, otherwise some unexpected falsey value might slip through. It might seem less applicable to the len(seq) case, but I'd offer that that's just an application of a more general principle.
This one is based on the preference for identity checks when singletons are involved, rather than equality tests. Being composed of English words, the latter is also more readable. It's the same reason why you would do identity checks against None or enum values.
I hope those explanations give you the basis for why the choices were made. They aren't arbitrary, although folks can and do disagree. It's much more important that your project comes up with its own guidelines and applies them self-consistently. For example, I have my own small set of refinements on top of PEP 8. I'm not providing a link because they're a bit out of date w.r.t. Python 3. ;) Cheers, -Barry
On Thu, Apr 24, 2014 at 7:11 AM, Skip Montanaro <skip@pobox.com> wrote:
I'm sorry, I have no recollection of such studies. (ABC used case differently anyway, so camelcase wasn't possible there -- and neither were underscores). Barry maybe referring to a more informal survey of feedback from Python users at the time. But I have no recollection of that either. -- --Guido van Rossum (python.org/~guido)
On 2014-04-24 14:59, Barry Warsaw wrote:
A more recent set of studies show some mixedResults (ha ha). On a low-level reading task, the studies agree with yours in that mixedCase takes more time and effort; however, it appears to improve accuracy as well. On a higher-level comprehension task, mixedCase took less or the same time and still improved accuracy. Experienced programmers don't see too much of a difference either way, but inexperienced programmers see a more marked benefit to mixedCase. http://www.cs.loyola.edu/~binkley/papers/tr-loy110720.pdf That said, I can't vouch for the experiments or the analysis, and it isn't really germane to Chris' historical question. I mention it only because I had just run across this paper last night, so it was fresh in my mind when you mentioned studies on the subject. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
One added note:
There is more to it that that -- == can be overridden for a particular class. So doing: X == None Could yield surprising results if __eq__ has been defined for the class X is bound to at the moment. Numpy arrays are a common case for me. As None is often used to mean undefined, X could be any type. Granted, in your code, you likely know what type(s) X is likely to be, but it's a good habit to get in to. -Chris
On Thu, Apr 24, 2014 at 4:59 PM, Barry Warsaw <barry@python.org> wrote:
I speak two languages as mother tongues - English and Hebrew. Hebrew has no capital letters (and is also right-to-left) and is the spoken and written language in the parts of Israel where I've lived most of my life. Perhaps because of this, I do find that capital letters don't quite "jump out" for me and therefore I find mixedCase and CamelCase harder to grok at a quick glance than under_score_names. - Tal
On Apr 24, 2014, at 06:51 PM, Tal Einat wrote:
I was musing at Pycon with others about how Go would handle identifiers in languages that don't have capital letters, such as Hebrew, given the fact that they use the case of the first letter to control identifier visibility. Their FAQ essentially punts on the issue (start your identifier with a letter that can be capitalized, e.g. X日本語) but says that this feature will likely stay. I guess it's Go's flavor of Python's whitespace rule. :) -Barry
On Thu, Apr 24, 2014 at 11:59 PM, Barry Warsaw <barry@python.org> wrote:
Underscores also play much more nicely with initialisms. How would you spell a function named "Add HTTP Header"? add_HTTP_header add_http_header addHTTPHeader addHttpHeader Four options to choose from. The first two clearly separate the initialism from the other words; take your pick whether you want it uppercased or not, because it's separated either way. In mixedCase, the first one merges the H of Header in with HTTP; with something less well known, that can be a nasty readability problem. The second one is probably more readable, but looks weird. Or, here's another one: converting one thing into another, where both are named by their initials: convert_XML_to_JSON convert_xml_to_json convertXMLToJSON convertXmlToJson Same four options. Which is the more readable? ChrisA
There's been a bit of serious study on this. The results are still open to interpretation, though ;-) Here's a nice summary: http://whathecode.wordpress.com/2011/02/10/camelcase-vs-underscores-scientif... of-course-dashes-are-most-natural-ly y'rs - tim On Thu, Apr 24, 2014 at 11:25 AM, Chris Angelico <rosuav@gmail.com> wrote:
[Tim]
[Terry Reedy]
The linked poll is almost evenly split, 52% to 48% for camel case with over 2000 votes each.
There are two polls in the post. You're referring to the first, which the author asked viewers to fill out before reading any of the "evidence". There's another poll at the end, which the author asked viewers to fill out after reading the whole post. In that poll, preference changed (56% to 44% in favor of underscore). A followup post summarized later research, confirming the earlier result that CamelCase'd names are harder to read (as measured by eye tracking studies): http://whathecode.wordpress.com/2013/02/16/camelcase-vs-underscores-revisite... but-all-obvious-a-priori-to-the-most-casual-observer<wink>-ly y'rs - tim
On Thu, Apr 24, 2014 at 11:36:03AM -0500, Tim Peters wrote:
To summarize the key points of the two papers referenced in this thread: Blinky 2009: Participants were trained in camelCase. camelCase was 13.5% slower, 51.5% more accurate on an identifying task. Sharif 2010: Participants were trained in underscores. Same accuracy, camelCase was 20% slower. It seems like, generalizing, camelCase is slower and more accurate, while training affects both speed and accuracy. But, really, there is no compelling scientific argument here. It really boils down to CONSISTENCY: 1) If the existing code uses one or the other, follow the original code to preserve CONSISTENCY. 2) If you're starting a new project, follow PEP8 (or the standards for the language you're using) to preserve CONSISTENCY.
On Fri, Apr 25, 2014 at 11:40 AM, Allen Li <cyberdupo56@gmail.com> wrote:
2) If you're starting a new project, follow PEP8 (or the standards for the language you're using) to preserve CONSISTENCY.
Don't forget that PEP 8 is not the standard for the Python language, only the Python stdlib. Particularly, there's no strong reason to follow some of its lesser advices (eg spaces rather than tabs, the exact maximum line length) for new projects; if all your developers have good quality screens, there's no point wrapping all your code to 79 just because the Python standard library is wrapped to 79. That particular example is touched on in the PEP itself (suggesting 20 more characters); you could easily set a maximum of 89, 99, or 159 characters if it makes sense for your project. Consistency with the standard library in names is slightly more useful, but the standard library isn't perfectly consistent itself (eg not all class names start with a capital), and if you're spending too much time arguing about style instead of getting code written, your style guide isn't doing its job :) ChrisA
On Apr 25, 2014, at 12:00 PM, Chris Angelico wrote:
I'd say it depends. If the code is going to be shared with people outside of your organization (e.g. open source libraries), then there's a strong motivation to be consistent throughout the community, which means PEP 8. -Barry
On 25/04/2014 04:03, Barry Warsaw wrote:
Right, so for me this means even in a private code base, there are big benefits to using PEP 8; everything looks the same, whether it's a third party library, python core or your own code... Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
On 25/04/2014 13:09, Chris Withers wrote:
I essentially had this conversation via my blog a couple of years ago: http://ramblings.timgolden.me.uk/2012/03/27/pep8-or-not/ http://ramblings.timgolden.me.uk/2012/03/29/more-on-pep8/ http://ramblings.timgolden.me.uk/2012/04/09/pep8-it-is-then/ and was quite surprised at the strength of feeling evoked. As you can even tell from the titles of the posts, I ended up by accepting that, even though I'm at liberty to apply my own format to my own code, it would be more of a community-friendly idea to use [near-enough] PEP8 regardless. As you can also see from the comments throughout, YMMV. :) TJG
Chris Withers writes:
On 25/04/2014 04:03, Barry Warsaw wrote:
Indeed. But channeling the FLUFL here, I would say that in your situation where people have already developed a large code base that apparently isn't shared much (if at all) outside the organization, they've already paid the price of nonconformity for the existing code base. If there's a formal standard, and you don't expect the "insiders only" policy to change soon (assuming it actually exists), I don't see why you would push for a change to PEP 8 at all. If you *don't* have a formal standard and existing code is a mixture of styles, I'd be very tempted to say "PEP 8 for new modules" (even if some of the mix is consistent -- for example all the ex-C++ programmers like CamelCase). Ditto if you're going to be developing modules to publish as OSS. And from *outside* of your organization, it's a no-brainer. PEP 8 is what Python itself and most 3rd party OSS modules use. Getting your people to use PEP 8 will make it a lot easier for them to learn to read Python core and stdlib code, and once they start reading --- why, the obvious next step is *contributing*. Yay! ;-)
On Apr 25, 2014, at 11:06 PM, Stephen J. Turnbull wrote:
And if you do deviate from PEP 8, I think it's quite helpful to publish a style guide outlining the deviations. It helps others contribute to your project. Of course, the first line of that style guide should be: `PEP 8`_ is the basis for this style guide so its recommendations should be followed except for the differences outlined here. :) cheers, -Barry
On 25 April 2014 10:36, Barry Warsaw <barry@python.org> wrote:
And if you're going to publish a tool to enforce your *personal* style guide and include your own custom rules that the "this is OK" examples in PEP 8 fail to satisfy, don't call it "pep8". Especially don't do that if you're then going to ignore a core developer that calls you on misappropriating python-dev's authority :( Regards, Nick. P.S. https://github.com/jcrocholl/pep8/issues/256 -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
2014-04-25 18:10 GMT+02:00 Nick Coghlan <ncoghlan@gmail.com>:
I am the current maintainer of this 'pep8' tool which was mentionned in a previous message. The tool was first published in 2006 by its original author. I take the feedbacks of the users in consideration, as much as I can. When something is unambiguously identified as a bug, I try to merge a patch in a timely manner. If it is an enhancement or a change of behavior, it is not in the priority list, of course. Two cases where signaled in the issue #256 last month, where the tool is arguably not compliant with some of the current conventions of the PEP. I've highlighted the reasons behind these checkers in the issue tracker directly. I disagree that they are in direct opposition with the PEP 8 coding conventions, though. The first concern is about 4 spaces indentation for continuation lines. For this point, the text of the PEP says "Use 4 spaces per indentation level", which lets room for interpretation (like some other parts of the PEP). However I changed some stuff in v1.5 to better isolate this case, so the user can add E121 safely to the ignore list: https://github.com/jcrocholl/pep8/blob/master/CHANGES.txt#L96-L105 The second concern is about compound statements, which are "generally discouraged" in the words of the PEP. Technically, there's no obvious way to implement "generally discouraged" in code. The compromise is to disable the check E701 and "use your own judgment" instead, if you feel it does not match you project's style guide. By the way, the example reported in #256 was only added last year to the PEP: def f(x): return 2*x And if we look closer to the PEP 8 history for the last two years (since March 2012), there were lots of changes and I've already updated the tool to catch up with some of them. However the tool has a large base of users, and I try to preserve some stability instead of removing features every time someone has an objection. In such case, what I recommend to the users is to configure the tool to ignore the checks which conflict with their own habits or conventions. I wrote some words in the documentation, one year ago, to explain what is the purpose of the tool and its limitations. There's no claim of any endorsement implicit or explicit by the PSF, the PSU or any other python developer :-) http://pep8.readthedocs.org/en/latest/intro.html#disclaimer I'm sorry if you felt that my previous answer was an offense to some python-dev authority, this is not intentional. Kind regards, -- Florent
On 04/25/2014 12:45 PM, Florent wrote:
The problem is that you've named it pep8. To me, that means I can run it and get PEP 8 results. If I have to add a manual configuration to get actual PEP 8 semantics, it's a buggy tool. For a similar example, I am the author/maintainer of enum34, which purports to be the backport of Python's 3.4 enum class. While I could go and make changes to it to better match my style, or even the styles of other users, calling it enum34 after that would be misleading as some one couldn't then switch from using enum34 in Python 3.2 to using the default enum in Python 3.4. If you had extra switches to turn on extra behavior, that would be fine. Leaving it as it is, and calling it something else would be fine. But as it stands now, with the name of pep8 and the behavior of failing on the PEP 8 document... well, that's false advertising. -- ~Ethan~
On 04/25/2014 01:55 PM, Ethan Furman wrote:
I think this fuss is unreasonable and unwarranted. I'd like to thank Florent for taking the time to maintain an extremely-useful tool that makes it feasible to keep to a consistent PEP 8 style throughout a large codebase with many contributors, and I think he should have the leeway as maintainer to make the necessary judgment calls about precisely which PEP 8 recommendations are reported precisely how by the tool, given that: - we aren't talking about real variance from the spirit or recommendations of PEP 8 (though you wouldn't know it from some of the rhetoric here about "personal preferences") - the tool makes it very easy to turn off whichever errors you don't prefer to enforce. - PEP 8 changes regularly (as Florent noted, the offending code example was only added recently), and there is value in the automated tool maintaining some stability for its users. Personally, I would much rather see pep8.py err on the side of being too strict with PEP 8's recommendations than too loose. Again, it's not hard to turn off the ones you don't want. If python-dev wants to control the precise behavior of pep8.py, bring it into the standard library and adopt maintenance of it. Otherwise, please give Florent some grace. Carl
On Apr 25, 2014, at 5:52 PM, Carl Meyer <carl@oddbird.net> wrote:
Carl’s post mirrors my own thoughts and it’s said much better than I could have. pep8.py doesn’t violate PEP8, it just takes a stricter view of it. ----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On 25 April 2014 18:26, Donald Stufft <donald@stufft.io> wrote:
In other words, it adds rules that have not been discussed on python-dev, and effectively claims that those rules are part of PEP 8 when they're not. Note that my problem is *specifically* with errors, and especially with errors that are on by default. Even with the name "pep8", warnings and below are clearly at the discretion of the tool authors and maintainers, and while "off-by-default" errors strike me as nonsensical (why not just make them warnings instead?), I also don't have a problem with adding more of them. However, keeping E121 (which requires all indentation of continued lines in expressions to also be a multiple of 4, rather than only semantically significant indentations) and E701 (which completely disallows the use of single line compound statements, even through the PEP text only discourages them) as errors rather than warnings is apparently more important than my wholehearted endorsement of the tool as a co-author of PEP 8. So be it - but while that is the case, pep8 is *not* a PEP 8 linter, it remains "PEP 8 plus extra rules python-dev has never discussed". Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
2014-04-26 0:46 GMT+02:00 Nick Coghlan <ncoghlan@gmail.com>:
You're a co-author of PEP 8 since less than a year. I'm the maintainer of the pep8 tool since 2010. You should probably read the LICENSE file which is shipped with the pep8 too, and the disclaimer that I've posted previously. Never I engage the responsibility of the authors of the PEP 8 document, and I don't give any guarantee of being a *strict* PEP 8 compliance tool. However, you should notice that your ticket in the tracker is opened for 2 months only, and I did not flagged it as being resolved. As I've stated in my previous mail, I give priority to bugs over other requests. And even if you think it is a critical bug for yourself, it did not appear like that for the thousands of people which used the library for the last few years. But if you read the documentation carefully, you can see that I've already excluded some checks from the default behavior in the previous releases, when there was an argument which was backed by the PEP 8 itself: "In the default configuration, the checks E123, E133, E226, E241 and E242 are ignored because they are not rules unanimously accepted, and PEP 8 does not enforce them." http://pep8.readthedocs.org/en/latest/intro.html#error-codes The question stay opened for issue #256 and codes E121 and E701. As I said before, they are not against PEP 8, they interpret some words. If you're nitpicking, you can probably reject half the checks of the pep8 tool with similar allegations.
I *want* to be able to recommend this tool universally. But at the moment, I cannot, as its name is a lie: it enforces rules I don't personally agree with.
Maybe I prefer you don't recommend it in the PEP 8 documentation if it means I'll be tied to your "personal preferences" and that I'll be forced to patch it every now and then when you change a line, or a punctuation in a PEP 8 example. At the end, I find you're a bit rude when you come to this project which is not endorsed by the PSF or any Python-Dev related entity and you say "this project is wrong, because the developer did not obey to me when I order to remove that feature". You're more sympathetic and less in a hurry when it comes to some languishing bug on b.p.o :-) If you're so impatient, let's fork it and put in in cpython/Tools/ I would not fight against it. Sincerely, -- Florent
On Apr 25, 2014, at 7:56 PM, Florent <florent.xicluna@gmail.com> wrote:
I agree that I’ve never taken the name to mean that you’re claiming any sort of endorsement. There are a *vast* number of projects that implement something that was defined somewhere else and I don’t think any reasonable person can assume that all of those tools are endorsed by the authors of what they are implementing.
----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On Fri, Apr 25, 2014 at 08:13:35PM -0400, Donald Stufft wrote:
I think that is wrong. "Endorsed" is the wrong word -- what's important is that if package PEP8 "checks for PEP 8 compliance", then if package PEP8 checks for foo, then people assume that foo-checking is specified by PEP 8 -- whether it does or not. If something claims to be "JSON", say, then most people would expect that by default it would implement the JSON standard rather than some tweaked version of almost JSON. If their JSON library fails to match the standard, a significant number of people will assume that the library's non-standard version *is* the standard. It may even become the de-facto standard, regardless of what the standard actually says, and so introduce ambiguity where there was none. E.g. consider browser's treatment of ISO-8859-1 as Windows-1252. People and corporations often take this sort of stuff really seriously, and I'm not surprised that Nick feels as strongly as he does. I would too. Try releasing a package using the name "iPhone" without Apple's approval: https://developer.apple.com/softwarelicensing/index.php In this case, I too would have assumed that a package calling itself "PEP8" checks for compliance with PEP 8, and that any differences between PEP 8 and the package is a bug in the package. Providing the ability to turn on or off checks, or make them more or less strict, is okay, but I would expect that by default it should check for PEP 8 compliance, exactly PEP 8 compliance, and nothing but PEP 8 compliance. -- Steven
On 25 April 2014 19:56, Florent <florent.xicluna@gmail.com> wrote:
I apologise for my impatience. As I stated in that issue, I really *want* to be able to uncritically endorse pep8 for use on new Python projects, as while I like pylint personally, I think it's too complicated (and noisy by default) to recommend its use outside large multi-developer projects where taking the time to set up a custom config file is likely to pay off. Hence it's frustrating to me that I can't currently recommend pep8 for this use case, as the default behaviour includes rules I disagree with (in particular, the ones that the examples in PEP 8 itself fail). I believe the combination of the implied endorsement from the name of the tool and an explicit endorsement from me saying "use this on your projects" would imply that I agree with *all* the default behaviour, and that simply isn't the case (E121 in particular is outright wrong, since it violates the approach of aligning indented lines with an opening parenthesis). It seemed simple enough to me to say "yes, that makes sense, we can make those warnings eventually, but it's not a high priority to do so". That would put it back on me to craft a pull request to make the change, and would be an entirely appropriate response when I'm asking other people to do extra work. That hasn't been my impression of the response I received to date though - my impression of the response has been "we don't care about your feelings". Defending PEP 8 against people who think it's overly prescriptive is irritating enough, without having to also figure out whether people are actually complaining about the PEP or about a tool I didn't help write :( Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 25 April 2014 21:29, Nick Coghlan <ncoghlan@gmail.com> wrote:
Note that I've now resumed this discussion on the pep8 issue tracker (including splitting out a separate RFE specifically relating to the new'ish guideline for handling of single line function definitions). My apologies to Florent specifically, and the list in general, for letting frustrations with unrelated issues boil over into impatience and unconstructive criticism of a fellow open source contributor's efforts. Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
I think the tool's name is unfortunate. The first time I heard about it I was having an in-person discussion with a developer who (I thought) said that "PEP 8" was okay with his code (which I knew couldn't be the case) but in fact he meant to say that (some configuration of) "pep8" didn't mind it. This took some time to sort out and it would have avoided if the tool had had a better name. That said I think it's a great tool. On Fri, Apr 25, 2014 at 4:20 PM, Ethan Furman <ethan@stoneleaf.us> wrote:
-- --Guido van Rossum (python.org/~guido)
2014-04-26 1:46 GMT+02:00 Guido van Rossum <guido@python.org>:
Thank you, Actually I did not choose the name. I just took over the project 4 years ago by accident because I had some pull requests languishing and the author of the project was no longer interested in it. I agree that the name is a source of confusion in some cases. I've mitigated some conflicts with PEP 8 by incitating contributors to write "flake8" extensions instead of pushing more features into "pep8" itself, and also I tried to define a default configuration which is "good enough" to support the PEP 8 recommendations. -- Florent
On Apr 25, 2014, at 7:20 PM, Ethan Furman <ethan@stoneleaf.us> wrote:
Not really, any code that passes the pep8.py check is perfectly valid in the eyes of PEP8, if a check was implemented to say, require camelCase method names, then that would be a violation of a check. Being stricter is not a violation, it’s being stricter. ----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On 04/25/2014 05:42 PM, Donald Stufft wrote:
Then it should be called stricterThanPep8. ;) I think we're going to have to agree to disagree on this point. A tool that implements PEP 8 [1], but tells me that something PEP 8 allows is an error -- well, that's not PEP 8 then, is it? At any rate, this part of the thread is pretty off-topic, so this is my last post about it. -- ~Ethan~ [1] Yes, I checked the site for pep8, and saw the escape clause of "some of the style conventions" -- the problem is the cognitive dissonance between the name of the tool and the actions of the tool.
On Fri, Apr 25, 2014 at 08:42:02PM -0400, Donald Stufft wrote:
Suppose that some package claiming to check for PEP 8 compliance decided to flag variable names like "foo" and "bar" as errors. Perhaps it was inspired by Tim Peters: Indeed, when I design my killer language, the identifiers "foo" and "bar" will be reserved words, never used, and not even mentioned in the reference manual. Any program using one will simply dump core without comment. Multitudes will rejoice. -- Tim Peters, 29 Apr 1998 Or perhaps it decides that one should never, ever have more than a single dot in a row, a treat that as an error: obj.method() # okay obj.method().attribute # Law Of Demeter violation This hypothetical checker is stricter than PEP 8, in that it allows nothing that PEP 8 forbids. But it also forbids things which are allowed by PEP 8, which is a false negative error: things which should be allowed (according to PEP 8) are forbidden by the checker. (The other kind of error is a false positive, where things which are forbidden by PEP 8 are wrongly allowed by the checker.) I stress that they're only errors if the checker is running in PEP 8 compatibility mode, where it is supposed to check for PEP 8 compliance. That's the crux of Nick's, and Ethan's, argument: with a name like "PEP8", it is reasonable to expect that by default the checker operates in PEP 8 compatibility mode. I agree with them. -- Steven
On 25 April 2014 17:52, Carl Meyer <carl@oddbird.net> wrote:
Yes we are. My name is on PEP 8 as one of the three co-authors, and my request to downgrade anything in the "pep8" tools that is not *explicitly* disallowed by the PEP to be a warning at most has been ignored. If you read the GitHub issue, you can see I *want* to be able to recommend this tool universally. But at the moment, I cannot, as its name is a lie: it enforces rules I don't personally agree with, yet claims to be based on a PEP I helped write. There is a way to get changes made to the common guidelines in PEP 8: you bring your case to python-dev and argue for the adoption of those rules in the standard library. If a tool doesn't claim to be speaking in my name, I don't care what rules it enforces. If a tool adds extra warnings, I also don't care. But "pep8" currently claims as errors code that is listed *in PEP 8 itself* as acceptable. I am *not* OK with that.
- the tool makes it very easy to turn off whichever errors you don't prefer to enforce.
This is about the default behaviour, and claiming as errors things that are explicitly listed in the PEP as OK.
No, this is exactly the *wrong* way to approach it. A tool laying claim to PEP 8's authority should err on the side of *not* enforcing rules that are not clearly rules - if more clarity is desired, then ask for clarity from python-dev.
Note that I don't complain about the default behaviour of pylint, pychecker, or any other linter tools. But by continuing to call the tool "pep8", Florent is claiming the endorsement of the PEP 8 authors and the consensus of python-dev for the tool's default behaviour (as noted above, this makes it personal for me, as I am a co-author of PEP 8). There is a very, very simple guideline that can be followed here: anything which is not clearly and unambiguously disallowed in the PEP itself should never be more than a warning in a tool that is called "pep8". Regards, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 4/25/2014 5:52 PM, Carl Meyer wrote:
- we aren't talking about real variance from the spirit or recommendations of PEP 8
So the one example under discussion is: foo = long_function_name( var_one, var_two, var_three, var_four) and comes from http://legacy.python.org/dev/peps/pep-0008/#indentation Specifically the third example with a heading of "Optional". From my reading of the text, plus all the other examples around it, I would have assumed the 2 space indent was simply a typo and should have indeed been 4 spaces. If this is really meant to show that indents other than 4 spaces are allowed in this situation maybe verbiage to that effect could be added. Janzert
On Sun, Apr 27, 2014 at 9:40 AM, Barry Warsaw <barry@python.org> wrote:
wow! just looked at that part of the PEP again, and that is a LOT of options. Is it impossible to come to any consensus on this? And as it happens, my favorite is not in there, though as far as I can tell not forbidden: foo = long_function_name(var_one, var_two, var_three, var_four) That is, I find that if the argument list is too long for one line, then splitting it out to only one argument per line is much more readable to me. This becomes more important with default parameters: foo = long_function_name(var_one, var_two=a_value, var_three=some_other_value, var_four=(a, tuple, of, values) ) as with more information in each argument, it's a lot more clear where one starts and the other begins. And it provides a nice place for comments: foo = long_function_name(var_one, var_two=a_value, # because default doesn't frobnicate in this case var_three=some_other_value, var_four=(a, tuple, of, values) ) Anyway -- is there a point in trying to standardize this a bit more in PEP8, or has that battle long since been fought and conceded ? -Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
On 4/27/2014 3:34 PM, Chris Barker wrote:
One arg per line is definitely permitted either when lining up with the first arg on the first line or with hanging indents.
In a fixed-pitch font, you have too many spaces for lines after the first. One advantage of hanging indent is that all arg lines have the same indent and thus the args line up regardless of the font. Hanging indents also give more space for default or named args and comments. I would agree with having at least one example done with one arg per line. -- Terry Jan Reedy
On Sun, Apr 27, 2014 at 04:28:20PM -0400, Terry Reedy wrote:
Is it really necessary? I think that one-arg-per-line is an obvious variation of the existing example. If the only example given was one-arg-per-line, then the reader might wrongly assume that *only* one arg was allowed. But since the example shows more than one arg per line (two in the above example), I expect that people will read it as "some arbitrary number" rather than "exactly two". So I don't think there's any need to show yet another example, especially since it's just a variation on the existing examples. -- Steven
On Sun, Apr 27, 2014 at 6:34 PM, Steven D'Aprano <steve@pearwood.info>wrote:
not really -- a lot of folks learn more from following examples. If all teh examples are the same in some aspect, we'll tend to think that that's intentional, and that is at least the recommended method....
If the only example given was one-arg-per-line, then the reader might wrongly assume that *only* one arg was allowed.
indeed -- but maybe less clear but the the fact that none of the examples show one argument per line, the implication is that that is discouraged. very had to document a widely variable standard! -Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
2014-04-27 21:34 GMT+02:00 Chris Barker <chris.barker@noaa.gov>:
FWIW, the tool pep8 has introduced continuation line indentation checks in 2012, based on the PEP 8 recommendations which were active at this date, and doing few extrapolations on cases which were not directly covered by the document (pep8.py v1.2, issue #64). Then we had a lot of iterations with the users of the library, and we've added more flexibility to cover the various styles which were in the spirit of PEP 8, and which give some added value for code readability. The end result of this work can be seen in the test suite : * more than 300 lines of rejected indentations: https://github.com/jcrocholl/pep8/blob/master/testsuite/E12.py * and more than 600 lines of acceptable cases: https://github.com/jcrocholl/pep8/blob/master/testsuite/E12not.py I don't think that the PEP 8 document should go in so much details, though. However these examples might help to have pragmatic discussions about which rules we want to recommend. Do not hesitate to give feedback here, or on the issue tracker. There's also a code-quality mailing-list which covers a little more than pep8.py: https://mail.python.org/mailman/listinfo/code-quality -- Florent
On Apr 27, 2014, at 12:34 PM, Chris Barker wrote:
Wow, do you really indent those 42 columns? This actually is forbidden because you're not using "vertical alignment" when there is an argument on the first line. You would have to line up `var_two` right under `var_one` to be compliant.
That is, I find that if the argument list is too long for one line, then splitting it out to only one argument per line is much more readable to me.
Sure. The PEP outlines ways to do that.
The only thing I see wrong (from a PEP 8 standpoint) with your example, is that your arguments are indented too far to the right. But e.g. this would be fine: foo = long_function_name(var_one, var_two=a_value, var_three=some_other_value, var_four=(a, tuple, of, values) ) Cheers, -Barry
On Sun, Apr 27, 2014 at 1:40 PM, Barry Warsaw <barry@python.org> wrote:
No -- stupid variable-width font! I don't think anyone should write code with variable width fonts, and I'd rather not do email that way either, but gmail is making it tough these days.. Sorry for the added confusion. This actually is forbidden because you're not using "vertical alignment"
yeah -- that was the intent.... oh well.
not really -- it allows it: # Aligned with opening delimiter. foo = long_function_name(var_one, var_two, var_three, var_four) but all the examples have more than one variable per line...my point is that I think that should be discouraged. i.e. I think the above should be: # Aligned with opening delimiter. foo = long_function_name(var_one, var_two, var_three, var_four) (done with fixed-width font this time -- but it may not look right in your mail reader..) though I doubt there would consensus on requiring that -- but many of us learn more from examples than the specification, so maybe I'll submit a patch with an example like that. -Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
On Apr 28, 2014, at 11:12 AM, Chris Barker wrote:
Ouch. I'm sure it's gmail being "helpful" the way <http://wiki.list.org/x/2IA9> is similarly helpful.
Fortunately, my mail stack is sane. :)
I also very much doubt you'd get consensus on that as a requirement, and I would oppose the PEP taking a stand one way or the other. I'm not sure that the PEP needs an example to illustrate its acceptability. Cheers, -Barry
On 4/28/2014 2:12 PM, Chris Barker wrote:
I don't think anyone should write code with variable width fonts,
The problem is that fixed pitch does not work well for even a half-way complete unicode font and I don't know that there are any available. As far as I know, my Windows 7 only came with one unicode font that Idle finds. An advantage from my viewpoint is that spaces in this font are narrower that the average character, making multiple-of-4 indents and spaces around operators look pretty good to me. Given that PEP8 generally disallows adding spaces to make things line up, as in the following (a style I used to adhere to) a = 134543344 # big number bonge = 2 # short number it seems to me consistent to use the multiple-of-4 hanging indent style and not try to make things line up with an odd number of spaces in this one special case. -- Terry Jan Reedy
R. David Murray writes:
My unix fix-width terminal font handles most unicode (even a lot of non-bmp stuff...though I have no idea if it is readable :).
Oh, I bet you do. With a true fixed-width Unicode font, it's the *Latin-character* text that's painful, if not unreadable, because the aspect ratio needs to be close to 1.0 to handle ideographs, rather than the 0.5 or less common with Latin fonts. XTerm has an option to treat ideographs as double width. That does the trick (at least, I don't know any scripts that really really want an aspect ratio of 0.7 or 2.0).
On Mon, Apr 28, 2014 at 3:01 PM, Terry Reedy <tjreedy@udel.edu> wrote:
...
Is ironic that that looks like hell in my variable-width font email client? it seems to me consistent to use the multiple-of-4 hanging indent style and
not try to make things line up with an odd number of spaces in this one special case.
things aren't going to generally line up with a non-fixed width font no matter how you slice it, so I guess if you need to use one for your code, you're just stuck. But I suppose the "line up with the opening bracket" style isn't a good idea in that case. All the more reason not to standardize anymore that PEP 8 already does. -Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
On Mon, Apr 28, 2014 at 11:12 AM, Chris Barker wrote:
I don't have a problem with discouraging it, but it should not be flagged in pep8 (OK in pep8 --wink-wink-nudge-nudge-say-no-more-eh, though!) I usually do use the style you prefer, especially when the arguments want to be commented, but in many cases the arguments are semantically tuples. Eg, rect1 = paint_rectangle(point[1], point[0], # top, left textheight + 2 * padding, textwidth + 2 * padding, chartreuse)
On 4/27/2014 12:40 PM, Barry Warsaw wrote:
Given the commits to pep 8 after this, I take it you decided the example really is correct. I'm glad the clarifying sentence got added and comment in the example changed, that should make it clear that the 2 space indent isn't a typo. Janzert
Carl Meyer writes:
I would too. N.B. Nick's complaints are a sort of left-handed compliment, too.
Of course. But whether an example in the PEP passes or not is *not* a judgment call at all, IMO. Do you think that it is?
That parenthetical remark was unnecessary, and at least in my case, I understood very well that there is no "real" variance. I disagree with the implied requirements, however. A program *intended to test standard conformance* MUST (in the sense of RFC 2119) aspire to a higher standard than "in the spirit", don't you think? Anyway, that's what I think.
- the tool makes it very easy to turn off whichever errors you don't prefer to enforce.
This is precisely backward. *I* have no errors I prefer to enforce or not to enforce. I want "PEP 8 conformance", I don't want to think or make judgments about individual recommendations in PEP 8. I want to leave that up to the PEP 8 maintainers. I suspect that is a common use case.
Achieving "some" stability would not be difficult: version the error sets of the tool, and provide a switch to invoke specific versions. Each version could be dated, as well, to allow such stability without knowing the precise content of the version of PEP 8 or pep8.py. I personally would not use such a switch, however. I would either change my code to conform to current PEP 8, or not. ;-)
Again, for many users of the tool, that is precisely *not* why they want to use the tool. They want to delegate the decision of which rules to enforce to the PEP 8 authors. Since *you* have preferences, I repeat your words back to you: it's not hard to turn on the ones you want. (Or it needn't be.)
Note that what Nick is complaining about is not that pep8.py varies from PEP 8 -- that's inevitable -- but rather that the variation is not *acknowledged* as a bug. So python-dev (but you really mean Nick) doesn't want to control the precise behavior of pep8.py, as code. What Nick wants is for code *bearing the name* to conform to the PEP it was named for. For users who want PEP 8 conformance merely because it is the standard, that's exactly right. For those of you who want to pick and choose which rules to follow and how strictly, the name doesn't much matter, does it? I think that in naming we should consider the use cases of those who depend on the name to be meaningful as higher priority than those who don't, but make their own judgments anyway. Regards,
Florent writes:
Of course there is an implicit claim of endorsement: the name. Read the TeX license -- pretty much the only restriction is *you can't call it "TeX" or any variation including that trademark if it doesn't pass TRIP*. When Don Knuth cares that much that names denote conformance to standard, Nick is in really good company. I agree 100% with Nick: in a program named "pep8", the examples in PEP 8 should *all* pass in the sense of not being labelled errors. Of course if the PEP changes that doesn't mean you should withdraw or rename the program, or even that you are required to address the issue within any time span. But you should consider it a bug. That said, issuing *warnings* for discouraged-but-sometimes-allowed practices is a great idea. A stricter warnings-are-errors *mode* is a good idea, especially for automated checkers, but it should be configurable for different policies.
Disclaimers are for lawyers. Other people assume names mean what they say.
On Apr 26, 2014, at 12:31 AM, Stephen J. Turnbull <stephen@xemacs.org> wrote:
No there isn’t. For instance there are things on PyPI named after websites, like github, twitter, Facebook, etc. These things are not written by the companies behind those websites and are merely written to interface with those websites. Should we assume that those companies all endorse every single one of those projects simply because they chose a descriptive name for their project? The name indicates what it attempts to do, create a PEP8 linter, it makes no claim of endorsement by the authors of the PEP. You can say it’s confusing if it’s named pep8 but doesn’t actually make it “PEP8”, but claiming it’s endorsement isn’t correct.
Or required to address it at all if you don’t wish to. Since the issue is still open I assume that means that the author hasn’t decided what the correct remediation is yet.
----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
Donald Stufft writes:
OK, "endorse" is an inappropriate word to describe the problem inherent in naming a script "pep8.py" when the maintainers of PEP 8 say it doesn't implement the PEP. (Aside: In fact, in the cases you cite, you *may* assume implicit approval (or that the company in question has not yet discovered and complained about the usage), if not active endorsement. That is the implication of a "trade name", and I suspect many of the names you mention are registered trademarks as well.) However, be that as it may, your examples are irrelevant to the "spirit" of Nick's issue: PEP 8 is a standard, not a corporate reputation. Even if there is no implicit "endorsement", the maintainer of the program is using the name of the document, while he and others are arguing that it's up to him to decide about conforming to it. That is unfair to those users who do not care about the *content* of the standard, but only about the interoperability implied by a certification of conformance to the standard. And if you think "interoperability" is a strong word to apply to a style guide like PEP 8, maybe so -- but RFC 2119 is also just a style guide, and I would hope that you would not argue that misuse of terms defined in that document has no interoperability consequences.
In the case of a explicit decision to WONTFIX just because you don't want to, it becomes a deliberately sustained false-y, and renaming is the appropriate action. There is a huge namespace of strings starting with "py". Although some of the more attractive ones are already taken (pylint, pychecker, pyflakes), I'm sure there's plenty of room for creative naming left if 100% conformance to the standard is a non-goal for the maintainer of the script.
Since the issue is still open I assume that means that the author hasn’t decided what the correct remediation is yet.
In the case of a program intended to check conformance to a standard, it's not a matter for the script maintainer's decision. It's obvious what the specification of the correct remediation is. (The author may of course choose the implementation. Or, having tried implementation he may decide to acknowledge the bug but WONTFIX it as too difficult, but too difficult is obviously not true here.) It's always possible that the document is buggy (as suggested by Janzert the 2- or 3- space indentation may have been a typo), but again, that's for the authors of the standard, not of the script, to decide.
On Fri, Apr 25, 2014 at 1:28 PM, Guido van Rossum <guido@python.org> wrote:
Hmm. There've been a good few conversations on python-list where people have been reminded that PEP 8 is *not* all that important for other projects (beyond that it's an already-written style guide - when you're starting a C project you can argue style guides for weeks, but when you start a Python project you can just say "PEP 8" and skip the bikeshedding), which I took to mean that it's on par with any other style guide; but looking at it the other way, it can be seen as a strong recommendation. I'm just not sure about the word "standard" there - to me a standard is something that you MUST follow, like RFCs for internet protocols. But that's just a matter of terminology, I guess. ChrisA
On 25/04/2014 03:00, Chris Angelico wrote:
I'm not sure I agree with that. PEP 8 *is* the standard for the language, in that there isn't anything else. Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
Fortunately, Unicode provides us with the COMBINING LOW LINE character, combining the horizontal space-savings of camelCase with the underscore-indicates-separation properties of _. And it's a valid Python identifier. convertx̲mlt̲oj̲son On Thu, Apr 24, 2014 at 12:25 PM, Chris Angelico <rosuav@gmail.com> wrote:
participants (26)
-
Allen Li -
Barry Warsaw -
Carl Meyer -
Chris Angelico -
Chris Barker -
Chris Barker - NOAA Federal
-
Chris Withers -
Daniel Holth -
Donald Stufft -
Ethan Furman -
Florent -
Glenn Linderman -
Greg Ewing -
Guido van Rossum -
Janzert -
Kristján Valur Jónsson -
Nick Coghlan -
R. David Murray -
Robert Kern -
Skip Montanaro -
Stephen J. Turnbull -
Steven D'Aprano -
Tal Einat -
Terry Reedy -
Tim Golden -
Tim Peters