Amend PEP-8 to require clear, understandable comments instead of Strunk & White Standard English comments
Hi all, this is a very small change, but I thought I would field it here to see if anyone has suggestions or ideas. Instead of requiring that comments be written in Strunk & White Standard English, PEP-8 should require instead that English-language comments be clear and easily understandable by other English speakers. This accomplishes the same goal without alienating or putting up barriers for people (especially people of color) whose native dialect of English is not Standard English. This change is a simple way to correct that while maintaining the original intent of the requirement. This change may even make the requirement more clear to people who are not familiar with Strunk & White, since for programmers, the main relevant aspect of that standard is "be clear and concise;" simply saying that instead of referencing Strunk & White may communicate this more effectively. Here is the current line in PEP-8: "When writing English, follow Strunk and White." I propose changing this line to "When writing English, ensure that your comments are clear and easily understandable to other English speakers."
Given I've never even heard of Strunk & White (my own privilege i'd assume)... yeah. I don't actually know what the existing "When writing English, follow Strunk and White." text in PEP-8 even means. It doesn't hyperlink to an online source for English style probably because this was written so long ago, but I wouldn't want it to anyways. People shouldn't be arguing about "proper" English within comments anyways. Is it readable to all involved and to the next folks involved (future selves included) who will read it several years later? Good enough. Perhaps just send a PR removing that sentence to simplify things? -gps On Fri, Jun 26, 2020 at 2:29 PM Keara Berlin <kearaberlin@gmail.com> wrote:
Your minor change is certainly an improvement. _The Elements of Style_ ( https://en.wikipedia.org/wiki/The_Elements_of_Style) is certainly a good text, but it's not even actually a style guide in the formal sense. On Fri, Jun 26, 2020 at 5:26 PM Keara Berlin <kearaberlin@gmail.com> wrote:
-- The dead increasingly dominate and strangle both the living and the not-yet born. Vampiric capital and undead corporate persons abuse the lives and control the thoughts of homo faber. Ideas, once born, become abortifacients against new conceptions.
On Fri, Jun 26, 2020 at 09:08:31PM -0000, Keara Berlin wrote:
"Clear and easily understandable" is subjective. What is clear and understandable to me may be impenetrably confusing to others, or obnoxiously dumbed down. Language that is clear and understandable to a Geordie, Brummie or Weegie could be incomprehensible to others. I've intentionally used only examples of white people here because this issue is not about "people of color" and it transcends parochial concerns about race. How would you feel about this as documentation for collections.deque? "If maxlen is set and the deque is chockers, appending a new item at one end will chuck out the item at the other end." That's perfectly clear and understandable to me and me mates. Strunk & White (which, by the way is not my first choice, not by a long, long way) at least offers a common standard that anyone can use, regardless of skin colour or native language. Far from putting up barriers, it levels the playing field by agreeing on a set of rules when we have a doubt about idiomatic written English. We don't have to engage in tedious arguments about whether Indian English or Singlish or Derry English or Pennsylvania Dutch English are "correct" or better or worse, we just have to agree on a set of rules to decide the troublesome cases. And this especially goes for people whose native tongue is no dialect of English at all, but a "foreign" language (except of course it's not foreign to them, English is the foreign language).
No, it doesn't accomplish the same goal. It strips us of a common set of standards and divides us instead of bringing us together. We have been remarkably light on arguments about grammar and spelling in the docs because we had a common standard. It is not a standard I like, and the American-centric spelling offends my sensibilities, but having a standard is better than on-going arguments about who is correct and who isn't.
That's prejudicial against neuro-atypical programmers (of whom there are many) who are not certain what *clear and concise* should mean. Clear and concise according to whom, according to what rules? I dislike Strunk and White, and don't follow it myself (except by accident, as it were) but I've worked with neuro-atypical programmers who found it really useful to have a common standard that they could follow and reduce the uncertainty of what makes for good writing. -- Steven
On Fri, Jun 26, 2020 at 9:43 PM Steven D'Aprano <steve@pearwood.info> wrote:
I agree. I would like to reinforce that many software engineers today are _not_ native English speakers but work with English codebases and write documentation in English. Any standard is better than just asking for "clear and easily understandable" and hoping that for some reason every person, no matter where they were born and how they learned English, will share your definition of "clear and easily understandable" by accident.
I can't say that I've ever assessed the quality of a code comment based on how well it adheres to Strunk & White, nor have I ever been involved with an environment that tries to strongly enforce that specific style of writing. So FWIW, I agree that "clear and concise English" is more relevant to most. On Fri, Jun 26, 2020 at 9:49 PM Guido van Rossum <guido@python.org> wrote:
On Sat, Jun 27, 2020 at 12:37:35AM -0400, David Mertz wrote:
Objectively, could I have dropped "most"? Both "most famous"?
Could you have dropped "still," objectively?
Yes, we probably could have. What's your point? I'm not arguing in favour of S&W here on this mailing list, and I've explicitly said that I don't even like their rules. But having a set of rules as (1) guidance for those who need guidance, especially those who have difficulty telling what is *clear and understandable to others*, and (2) for use in disputes, is not a bad thing. -- Steven
My point is that _Elements of Style_ is not a set of rules. It's a nice book with generally good advice; it's not a style guide in a formal sense. If we wanted rules, _The Chicago Manual of Style_ or the_Associated Press Style Guide_ would be much closer to that. But neither of those actually removes subjectivity about what's clear either. On Sat, Jun 27, 2020, 1:24 AM Steven D'Aprano <steve@pearwood.info> wrote:
Can I suggest an addition to this discussion that the phrase: "Must adhere to python community guidelines" otherwise it is possible to be disrespectful, abusive, sexist, etc., while being clean and understandable (and even adhering strictly to Strunk & White). It is completely possible to be hateful in many ways while sticking to any grammatical rules. A possible example (taken from some real commercial code that the customer would be taking delivery of): "This function is a drop in replacement for the complete waste of space originally written by <anatomically accurate but improbable description> <full name of original coder>." - (when I found this in the code base I did manage to get it replaced but not without resistance from some parties). Personally I think that community guidelines is better than trying to spell out what is unacceptable in a document such as PEP-8. Steve Barnes -----Original Message----- From: Greg Ewing <greg.ewing@canterbury.ac.nz> Sent: 27 June 2020 07:09 To: python-ideas@python.org Subject: [Python-ideas] Re: Amend PEP-8 to require clear, understandable comments instead of Strunk & White Standard English comments On 27/06/20 5:30 pm, David Mertz wrote:
Also, does it actually say anything that would forbid or discourage use of terms such as "chocker" and "chuck out"? -- Greg _______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-leave@python.org https://mail.python.org/mailman3/lists/python-ideas.python.org/ Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/2YJHM7... Code of Conduct: http://python.org/psf/codeofconduct/
On Sat, Jun 27, 2020 at 4:59 PM Steve Barnes <GadgetSteve@live.co.uk> wrote:
Can I suggest an addition to this discussion that the phrase: "Must adhere to python community guidelines" otherwise it is possible to be disrespectful, abusive, sexist, etc., while being clean and understandable (and even adhering strictly to Strunk & White). It is completely possible to be hateful in many ways while sticking to any grammatical rules. A possible example (taken from some real commercial code that the customer would be taking delivery of): "This function is a drop in replacement for the complete waste of space originally written by <anatomically accurate but improbable description> <full name of original coder>." - (when I found this in the code base I did manage to get it replaced but not without resistance from some parties).
Personally I think that community guidelines is better than trying to spell out what is unacceptable in a document such as PEP-8.
IMO the community guidelines are orthogonal to the style guide. You can be offensive while still maintaining the spacing, punctuation, and capitalization mandated by PEP 8, or you can be fully courteous in your language but mess up the style. People are expected to maintain both standards independently. I think there's a level of "formality" or "professionalism" that is expected (or presumed) here, but I don't know any easy way to define it. How do you say "comments have to use precise English" without the metaproblem of the expectation being itself imprecise? ChrisA
On Sat, Jun 27, 2020 at 2:44 PM Soni L. <fakedme+py@gmail.com> wrote:
Take word out of sentence, does sentence still mean same? Then word needless. Is objective test.
That sounds like the way the Heavy Weapons Guy talks (when he speaks English - his native language is Russian). What you've done is make a sentence that isn't grammatically correct, but can be interpreted unambiguously, which isn't the same thing. But if we want to debate linguistics, we should probably move to python-list... or to Savoynet, which does a pretty good job of arguing minutiae in the English language. ChrisA
On 27/06/20 4:33 pm, Steven D'Aprano wrote:
Take the word out of the sentence, and does the sentence still mean the same thing? Then the word was needless. That's an objective test.
But in something a fuzzy as natural language, "the same thing" is not a boolean value. How close in meaning does it have to be? Different people will have different opinions. -- Greg
Keara Berlin writes:
That's the same thing ("clear and understandable writing" is the purpose of _The Elements of Style_), except that Strunk and White provide guidelines as to *how* to make your writing "clear and easily understandable". This is useful to non-native speakers, and perhaps to others. It was to me when I encountered the book in 1971 or so, and later additions have taken their place beside it as they appeared. I wouldn't object to When writing English, write clearly and understandably. Consider your audience -- many readers of your comments in Python sources will be non-native speakers. "The Elements of Style" by Strunk and White provides a set of guidelines some consider useful in writing clearly and understandably. Steve Barnes suggestion of referring to community standards might be good too. I was peripherally involved in a situation that involved removing all references to "brain damage" from a medium size code base once. OTOH, I doubt that phrase would pass review in Python, ever. David Mertz points out that all of the rules in Strunk and White require subjective decisions. It's true that in any writing (even Mad Libs), eventually all decisions are subjective. However, "clear and understandable" is an aggregated level of subjectivity, while the individual principles (there are about 40 of them) in Strunk and White may be easier to grasp for most people. They certainly were for me. Whether that third sentence in my suggested wording is appropriate for PEP 8 is not my decision. But the reference to Strunk and White is the kind of quirky thing that endears Python to me, beyond it being a great community and a language full of wonders and practical use. I would be sad to see it deleted. Steve
On 27/06/2020 10:35, Stephen J. Turnbull wrote:
It is useful to recommend a guide to plain, comprehensible writing. Other guides are available (I've a soft spot for Gowers). Guido informs us S&W rules were not being enforced as a requirement by reviewers, and we've all been ok with that. I don't think anyone on the thread said they should. So that is the argument for removal of the requirement.
Then be sad. Turns out we are discussing a new idea: "Recommend a guide to writing clear comments in PEP-8". Fait accomplis: https://github.com/python/peps/commit/0c6427dcec1e98ca0bd46a876a7219ee4a9347...) Steven D'Aprano writes: """Language that is clear and understandable to a Geordie, Brummie or Weegie could be incomprehensible to others. I've intentionally used only examples of white people here because this issue is not about "people of color" and it transcends parochial concerns about race.""" And the conclusion is right, but the argument is better than he makes it. I've no idea what a Weegie is, but Brum is just up the road from where I write, and I can tell you only about 60% of Brummies class themselves as white. A high proportion of those that don't are yet native speakers of English, often in the distinctive Black Country accent that some scholars think was Shakespeare's. Those who hope to be understood widely, in my experience, moderate their use of regional words, but it's grand to add a bit of local colour now and then. Now the commit message is the thing that causes me to write. It contains a long justification for the change. It need only have said that we've decided not to enforce S&W rules. It is somewhat offensive, since it asserts as fact an opinion the community evidently does not hold universally, which is that the recommendation to use a standard form of English is "upholding relics of white supremacy". I get that S&W is a bit American, but recommending this or another resource does not make someone a white supremacist. I regret that this disagreeable view has made its way into the record. Arguments have been made in this thread that taking care to be clear in our writing is an inclusive act, and in fact the paragraph that follows the amended one makes a similar point. That so many of us speak and read some form of English at all is a relic of British supremacy and an effect of recent American supremacy. It is unfortunate, from the perspective of universal communication, that other languages exist at all, although enriching in other ways. It's just history and where we are. PEP-8 chooses to require English in comments [1]. In view of this, the use in the amended text of "other speakers of the language you are writing in" is needlessly complicated. It contains, let's remember, "coding conventions for the Python code comprising the standard library in the main Python distribution", for which English has been chosen, and those who use it for something else should adapt it. I know that in Python sometimes you have to be Dutch, but fortunately not when writing comments: that would be a barrier to contributing. I'm in luck. There is a lot of righteous anger just now about a class of long-standing injustices world-wide, and recent ones in the US, that colours the discussion. It is very difficult to address any argument, however weak, that starts from this anger, because of the risk it will be construed as disagreeing with the starting point, but please try to be tolerant of reason. I do not disagree with the values motivating efforts to be more inclusive. The Python community is exemplary in its intention to be inclusive, but here we are made afraid to say directly "please write in English and here is as a guide to doing so clearly", apparently because it is "putting up barriers for people whose native dialect of English is not Standard". There is no one standard English, but there is a range of broadly accepted, educated English. The guide is cheap, so the accusation of exclusivity must be the assumed cultural imperialism of asking people to write this educated English. The argument leads to "everyone should be free to write in their own variant of English, with no consideration for readers". It just wasn't pursued this far. Still, the outcome is less good for inclusivity than it might have been, because the means to achieve parity are now (in a trivial way) made less accessible. Jeff Allen [1] Strictly read, only "Python coders from non-English speaking countries" are required to write comments in English. So the rest of us ... exprimons-nous librement!
On Sun, Jun 28, 2020, 10:19 AM Jeff Allen
The commit message is simply silly. It introduces numerous contentious and false claims that have nothing whatsoever to do with the small wording change. It misunderstands how language, culture, history, and indeed white supremacism, work. I would recommend amending the commit message. The underlying change itself is reasonable, and to my mind a small improvement. There was unnecessary specificity in using Strunk and White as reference, and not, say, William Zinsser's _On Writing Well_, which is almost as well known. In the concrete, it would be exceedingly rare for these to provide conflicting advice on a specific code comment.
From: https://github.com/python/peps/commit/0c6427dcec1e98ca0bd46a876a7219ee4a9347...
This has nothing to do with making the wording "clear and understandable" (I agree on that). It's about, once again, bringing race-based politics into Python, and spreading hate towards a specific group of people: whites. Whether you're aware of it or not, there is a term for this: it's racism. I want to remind everyone that most of us here simply want to contribute code. We do it for free, and don't want to be involved in "this", because frankly it's disgusting. Doing something out of passion and for free, and at the same time seeing these sorts of things happening on a regular basis, looks and feels like an insult, and will only lead to people leaving this place. On Fri, Jun 26, 2020 at 11:27 PM Keara Berlin <kearaberlin@gmail.com> wrote:
-- Giampaolo - gmpy.dev <https://gmpy.dev/about>
Hello, Shouldn't such feedback be also cross-posted to the python-dev mailing list? Also note the original pull request, https://github.com/python/peps/pull/1470, and differences of what was written in the pull request description and what went in the commit message. On Sun, 28 Jun 2020 22:10:14 +0200 "Giampaolo Rodola'" <g.rodola@gmail.com> wrote:
-- Best regards, Paul mailto:pmiscml@gmail.com
Hi all, I didn't mean for there to be significant differences between what I posted here versus in the commit message. Sorry for any confusion around that! Thank you for putting them both in one place here - that is helpful. Take care, Keara On Sun, Jun 28, 2020, 16:12 Paul Sokolovsky <pmiscml@gmail.com> wrote:
On 6/28/2020 4:10 PM, Giampaolo Rodola' wrote:
Really, I would hate to see this list descend into voluminous discussions on racism. I haven't seen an comments yet that agreed with the OP that PEP 8 authors wrote anything racist. If fact, I suspect the authors would vehemently deny such an accusation. Please, can we just drop this discussion? --Edwin
Given I've never even heard of Strunk & White (my own privilege i'd assume)... yeah. I don't actually know what the existing "When writing English, follow Strunk and White." text in PEP-8 even means. It doesn't hyperlink to an online source for English style probably because this was written so long ago, but I wouldn't want it to anyways. People shouldn't be arguing about "proper" English within comments anyways. Is it readable to all involved and to the next folks involved (future selves included) who will read it several years later? Good enough. Perhaps just send a PR removing that sentence to simplify things? -gps On Fri, Jun 26, 2020 at 2:29 PM Keara Berlin <kearaberlin@gmail.com> wrote:
Your minor change is certainly an improvement. _The Elements of Style_ ( https://en.wikipedia.org/wiki/The_Elements_of_Style) is certainly a good text, but it's not even actually a style guide in the formal sense. On Fri, Jun 26, 2020 at 5:26 PM Keara Berlin <kearaberlin@gmail.com> wrote:
-- The dead increasingly dominate and strangle both the living and the not-yet born. Vampiric capital and undead corporate persons abuse the lives and control the thoughts of homo faber. Ideas, once born, become abortifacients against new conceptions.
On Fri, Jun 26, 2020 at 09:08:31PM -0000, Keara Berlin wrote:
"Clear and easily understandable" is subjective. What is clear and understandable to me may be impenetrably confusing to others, or obnoxiously dumbed down. Language that is clear and understandable to a Geordie, Brummie or Weegie could be incomprehensible to others. I've intentionally used only examples of white people here because this issue is not about "people of color" and it transcends parochial concerns about race. How would you feel about this as documentation for collections.deque? "If maxlen is set and the deque is chockers, appending a new item at one end will chuck out the item at the other end." That's perfectly clear and understandable to me and me mates. Strunk & White (which, by the way is not my first choice, not by a long, long way) at least offers a common standard that anyone can use, regardless of skin colour or native language. Far from putting up barriers, it levels the playing field by agreeing on a set of rules when we have a doubt about idiomatic written English. We don't have to engage in tedious arguments about whether Indian English or Singlish or Derry English or Pennsylvania Dutch English are "correct" or better or worse, we just have to agree on a set of rules to decide the troublesome cases. And this especially goes for people whose native tongue is no dialect of English at all, but a "foreign" language (except of course it's not foreign to them, English is the foreign language).
No, it doesn't accomplish the same goal. It strips us of a common set of standards and divides us instead of bringing us together. We have been remarkably light on arguments about grammar and spelling in the docs because we had a common standard. It is not a standard I like, and the American-centric spelling offends my sensibilities, but having a standard is better than on-going arguments about who is correct and who isn't.
That's prejudicial against neuro-atypical programmers (of whom there are many) who are not certain what *clear and concise* should mean. Clear and concise according to whom, according to what rules? I dislike Strunk and White, and don't follow it myself (except by accident, as it were) but I've worked with neuro-atypical programmers who found it really useful to have a common standard that they could follow and reduce the uncertainty of what makes for good writing. -- Steven
On Fri, Jun 26, 2020 at 9:43 PM Steven D'Aprano <steve@pearwood.info> wrote:
I agree. I would like to reinforce that many software engineers today are _not_ native English speakers but work with English codebases and write documentation in English. Any standard is better than just asking for "clear and easily understandable" and hoping that for some reason every person, no matter where they were born and how they learned English, will share your definition of "clear and easily understandable" by accident.
I can't say that I've ever assessed the quality of a code comment based on how well it adheres to Strunk & White, nor have I ever been involved with an environment that tries to strongly enforce that specific style of writing. So FWIW, I agree that "clear and concise English" is more relevant to most. On Fri, Jun 26, 2020 at 9:49 PM Guido van Rossum <guido@python.org> wrote:
On Sat, Jun 27, 2020 at 12:37:35AM -0400, David Mertz wrote:
Objectively, could I have dropped "most"? Both "most famous"?
Could you have dropped "still," objectively?
Yes, we probably could have. What's your point? I'm not arguing in favour of S&W here on this mailing list, and I've explicitly said that I don't even like their rules. But having a set of rules as (1) guidance for those who need guidance, especially those who have difficulty telling what is *clear and understandable to others*, and (2) for use in disputes, is not a bad thing. -- Steven
My point is that _Elements of Style_ is not a set of rules. It's a nice book with generally good advice; it's not a style guide in a formal sense. If we wanted rules, _The Chicago Manual of Style_ or the_Associated Press Style Guide_ would be much closer to that. But neither of those actually removes subjectivity about what's clear either. On Sat, Jun 27, 2020, 1:24 AM Steven D'Aprano <steve@pearwood.info> wrote:
Can I suggest an addition to this discussion that the phrase: "Must adhere to python community guidelines" otherwise it is possible to be disrespectful, abusive, sexist, etc., while being clean and understandable (and even adhering strictly to Strunk & White). It is completely possible to be hateful in many ways while sticking to any grammatical rules. A possible example (taken from some real commercial code that the customer would be taking delivery of): "This function is a drop in replacement for the complete waste of space originally written by <anatomically accurate but improbable description> <full name of original coder>." - (when I found this in the code base I did manage to get it replaced but not without resistance from some parties). Personally I think that community guidelines is better than trying to spell out what is unacceptable in a document such as PEP-8. Steve Barnes -----Original Message----- From: Greg Ewing <greg.ewing@canterbury.ac.nz> Sent: 27 June 2020 07:09 To: python-ideas@python.org Subject: [Python-ideas] Re: Amend PEP-8 to require clear, understandable comments instead of Strunk & White Standard English comments On 27/06/20 5:30 pm, David Mertz wrote:
Also, does it actually say anything that would forbid or discourage use of terms such as "chocker" and "chuck out"? -- Greg _______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-leave@python.org https://mail.python.org/mailman3/lists/python-ideas.python.org/ Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/2YJHM7... Code of Conduct: http://python.org/psf/codeofconduct/
On Sat, Jun 27, 2020 at 4:59 PM Steve Barnes <GadgetSteve@live.co.uk> wrote:
Can I suggest an addition to this discussion that the phrase: "Must adhere to python community guidelines" otherwise it is possible to be disrespectful, abusive, sexist, etc., while being clean and understandable (and even adhering strictly to Strunk & White). It is completely possible to be hateful in many ways while sticking to any grammatical rules. A possible example (taken from some real commercial code that the customer would be taking delivery of): "This function is a drop in replacement for the complete waste of space originally written by <anatomically accurate but improbable description> <full name of original coder>." - (when I found this in the code base I did manage to get it replaced but not without resistance from some parties).
Personally I think that community guidelines is better than trying to spell out what is unacceptable in a document such as PEP-8.
IMO the community guidelines are orthogonal to the style guide. You can be offensive while still maintaining the spacing, punctuation, and capitalization mandated by PEP 8, or you can be fully courteous in your language but mess up the style. People are expected to maintain both standards independently. I think there's a level of "formality" or "professionalism" that is expected (or presumed) here, but I don't know any easy way to define it. How do you say "comments have to use precise English" without the metaproblem of the expectation being itself imprecise? ChrisA
On Sat, Jun 27, 2020 at 2:44 PM Soni L. <fakedme+py@gmail.com> wrote:
Take word out of sentence, does sentence still mean same? Then word needless. Is objective test.
That sounds like the way the Heavy Weapons Guy talks (when he speaks English - his native language is Russian). What you've done is make a sentence that isn't grammatically correct, but can be interpreted unambiguously, which isn't the same thing. But if we want to debate linguistics, we should probably move to python-list... or to Savoynet, which does a pretty good job of arguing minutiae in the English language. ChrisA
On 27/06/20 4:33 pm, Steven D'Aprano wrote:
Take the word out of the sentence, and does the sentence still mean the same thing? Then the word was needless. That's an objective test.
But in something a fuzzy as natural language, "the same thing" is not a boolean value. How close in meaning does it have to be? Different people will have different opinions. -- Greg
Keara Berlin writes:
That's the same thing ("clear and understandable writing" is the purpose of _The Elements of Style_), except that Strunk and White provide guidelines as to *how* to make your writing "clear and easily understandable". This is useful to non-native speakers, and perhaps to others. It was to me when I encountered the book in 1971 or so, and later additions have taken their place beside it as they appeared. I wouldn't object to When writing English, write clearly and understandably. Consider your audience -- many readers of your comments in Python sources will be non-native speakers. "The Elements of Style" by Strunk and White provides a set of guidelines some consider useful in writing clearly and understandably. Steve Barnes suggestion of referring to community standards might be good too. I was peripherally involved in a situation that involved removing all references to "brain damage" from a medium size code base once. OTOH, I doubt that phrase would pass review in Python, ever. David Mertz points out that all of the rules in Strunk and White require subjective decisions. It's true that in any writing (even Mad Libs), eventually all decisions are subjective. However, "clear and understandable" is an aggregated level of subjectivity, while the individual principles (there are about 40 of them) in Strunk and White may be easier to grasp for most people. They certainly were for me. Whether that third sentence in my suggested wording is appropriate for PEP 8 is not my decision. But the reference to Strunk and White is the kind of quirky thing that endears Python to me, beyond it being a great community and a language full of wonders and practical use. I would be sad to see it deleted. Steve
On 27/06/2020 10:35, Stephen J. Turnbull wrote:
It is useful to recommend a guide to plain, comprehensible writing. Other guides are available (I've a soft spot for Gowers). Guido informs us S&W rules were not being enforced as a requirement by reviewers, and we've all been ok with that. I don't think anyone on the thread said they should. So that is the argument for removal of the requirement.
Then be sad. Turns out we are discussing a new idea: "Recommend a guide to writing clear comments in PEP-8". Fait accomplis: https://github.com/python/peps/commit/0c6427dcec1e98ca0bd46a876a7219ee4a9347...) Steven D'Aprano writes: """Language that is clear and understandable to a Geordie, Brummie or Weegie could be incomprehensible to others. I've intentionally used only examples of white people here because this issue is not about "people of color" and it transcends parochial concerns about race.""" And the conclusion is right, but the argument is better than he makes it. I've no idea what a Weegie is, but Brum is just up the road from where I write, and I can tell you only about 60% of Brummies class themselves as white. A high proportion of those that don't are yet native speakers of English, often in the distinctive Black Country accent that some scholars think was Shakespeare's. Those who hope to be understood widely, in my experience, moderate their use of regional words, but it's grand to add a bit of local colour now and then. Now the commit message is the thing that causes me to write. It contains a long justification for the change. It need only have said that we've decided not to enforce S&W rules. It is somewhat offensive, since it asserts as fact an opinion the community evidently does not hold universally, which is that the recommendation to use a standard form of English is "upholding relics of white supremacy". I get that S&W is a bit American, but recommending this or another resource does not make someone a white supremacist. I regret that this disagreeable view has made its way into the record. Arguments have been made in this thread that taking care to be clear in our writing is an inclusive act, and in fact the paragraph that follows the amended one makes a similar point. That so many of us speak and read some form of English at all is a relic of British supremacy and an effect of recent American supremacy. It is unfortunate, from the perspective of universal communication, that other languages exist at all, although enriching in other ways. It's just history and where we are. PEP-8 chooses to require English in comments [1]. In view of this, the use in the amended text of "other speakers of the language you are writing in" is needlessly complicated. It contains, let's remember, "coding conventions for the Python code comprising the standard library in the main Python distribution", for which English has been chosen, and those who use it for something else should adapt it. I know that in Python sometimes you have to be Dutch, but fortunately not when writing comments: that would be a barrier to contributing. I'm in luck. There is a lot of righteous anger just now about a class of long-standing injustices world-wide, and recent ones in the US, that colours the discussion. It is very difficult to address any argument, however weak, that starts from this anger, because of the risk it will be construed as disagreeing with the starting point, but please try to be tolerant of reason. I do not disagree with the values motivating efforts to be more inclusive. The Python community is exemplary in its intention to be inclusive, but here we are made afraid to say directly "please write in English and here is as a guide to doing so clearly", apparently because it is "putting up barriers for people whose native dialect of English is not Standard". There is no one standard English, but there is a range of broadly accepted, educated English. The guide is cheap, so the accusation of exclusivity must be the assumed cultural imperialism of asking people to write this educated English. The argument leads to "everyone should be free to write in their own variant of English, with no consideration for readers". It just wasn't pursued this far. Still, the outcome is less good for inclusivity than it might have been, because the means to achieve parity are now (in a trivial way) made less accessible. Jeff Allen [1] Strictly read, only "Python coders from non-English speaking countries" are required to write comments in English. So the rest of us ... exprimons-nous librement!
On Sun, Jun 28, 2020, 10:19 AM Jeff Allen
The commit message is simply silly. It introduces numerous contentious and false claims that have nothing whatsoever to do with the small wording change. It misunderstands how language, culture, history, and indeed white supremacism, work. I would recommend amending the commit message. The underlying change itself is reasonable, and to my mind a small improvement. There was unnecessary specificity in using Strunk and White as reference, and not, say, William Zinsser's _On Writing Well_, which is almost as well known. In the concrete, it would be exceedingly rare for these to provide conflicting advice on a specific code comment.
From: https://github.com/python/peps/commit/0c6427dcec1e98ca0bd46a876a7219ee4a9347...
This has nothing to do with making the wording "clear and understandable" (I agree on that). It's about, once again, bringing race-based politics into Python, and spreading hate towards a specific group of people: whites. Whether you're aware of it or not, there is a term for this: it's racism. I want to remind everyone that most of us here simply want to contribute code. We do it for free, and don't want to be involved in "this", because frankly it's disgusting. Doing something out of passion and for free, and at the same time seeing these sorts of things happening on a regular basis, looks and feels like an insult, and will only lead to people leaving this place. On Fri, Jun 26, 2020 at 11:27 PM Keara Berlin <kearaberlin@gmail.com> wrote:
-- Giampaolo - gmpy.dev <https://gmpy.dev/about>
Hello, Shouldn't such feedback be also cross-posted to the python-dev mailing list? Also note the original pull request, https://github.com/python/peps/pull/1470, and differences of what was written in the pull request description and what went in the commit message. On Sun, 28 Jun 2020 22:10:14 +0200 "Giampaolo Rodola'" <g.rodola@gmail.com> wrote:
-- Best regards, Paul mailto:pmiscml@gmail.com
Hi all, I didn't mean for there to be significant differences between what I posted here versus in the commit message. Sorry for any confusion around that! Thank you for putting them both in one place here - that is helpful. Take care, Keara On Sun, Jun 28, 2020, 16:12 Paul Sokolovsky <pmiscml@gmail.com> wrote:
On 6/28/2020 4:10 PM, Giampaolo Rodola' wrote:
Really, I would hate to see this list descend into voluminous discussions on racism. I haven't seen an comments yet that agreed with the OP that PEP 8 authors wrote anything racist. If fact, I suspect the authors would vehemently deny such an accusation. Please, can we just drop this discussion? --Edwin
participants (17)
-
Bernardo Sulzbach -
Chris Angelico -
David Mertz -
Edwin Zimmerman -
Giampaolo Rodola' -
Greg Ewing -
Gregory P. Smith -
Guido van Rossum -
Jeff Allen -
Keara Berlin -
Kyle Stanley -
MRAB -
Paul Sokolovsky -
Soni L. -
Stephen J. Turnbull -
Steve Barnes -
Steven D'Aprano