On Fri, Jun 26, 2020 at 9:43 PM Steven D'Aprano steve@pearwood.info wrote:

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.

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:

Steven just likes an argument. Nobody has ever taken the idea of a standard for language in comments seriously. It Just doen come up.

On Fri, Jun 26, 2020 at 18:35 Bernardo Sulzbach bernardo@bernardosulzbach.com wrote:

...

On Fri, Jun 26, 2020 at 9:43 PM Steven D'Aprano steve@pearwood.info wrote:

...

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.

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. _______________________________________________ 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/3MOO4L... Code of Conduct: http://python.org/psf/codeofconduct/

-- --Guido (mobile) _______________________________________________ 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/XG4J5U... Code of Conduct: http://python.org/psf/codeofconduct/

On Fri, Jun 26, 2020 at 11:36:47PM -0400, David Mertz wrote:

On Fri, Jun 26, 2020, 8:40 PM Steven D'Aprano steve@pearwood.info wrote:

...

"Clear and easily understandable" is subjective. What is clear and understandable to me may be impenetrably confusing to others, or obnoxiously dumbed down.

Strunk and White's most famous mandate of "omit needless words" is likewise subjective.

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.

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.

On 27/06/20 5:30 pm, David Mertz wrote:

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.

Also, does it actually say anything that would forbid or discourage use of terms such as "chocker" and "chuck out"?

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/2020 10:35, Stephen J. Turnbull wrote:

Keara Berlin writes:

...

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."

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 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.

... 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.

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

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".

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.

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:

From: https://github.com/python/peps/commit/0c6427dcec1e98ca0bd46a876a7219ee4a9347...

...

Instead of requiring that comments be written in Strunk & White Standard

English, require instead that English-language comments be clear and easily understandable by other English speakers. This accomplishes the same goal without upholding relics of white supremacy. Many native English speakers do not use Standard English as their native dialect, so requiring conformation to Standard English centers whiteness in an inappropriate and unnecessary way, and can alienate and put up barriers for people of color and those 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 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:

...

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." _______________________________________________ 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/AE2M7K... Code of Conduct: http://python.org/psf/codeofconduct/

-- Giampaolo - gmpy.dev https://gmpy.dev/about

On 6/28/2020 4:10 PM, Giampaolo Rodola' wrote:

From: https://github.com/python/peps/commit/0c6427dcec1e98ca0bd46a876a7219ee4a9347...

...

Instead of requiring that comments be written in Strunk & White Standard English, require instead that English-language comments be clear and easily understandable by other English speakers. This accomplishes the same goal without upholding relics of white supremacy. Many native English speakers do not use Standard English as their native dialect, so requiring conformation to Standard English centers whiteness in an inappropriate and unnecessary way, and can alienate and put up barriers for people of color and those 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 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.

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