date:20200704

Caveats:
- Any expression (unless you allow reference to variables previously bound
by the match statement) can just be aliased (as long as you don’t need
short circuiting), so it’s not a critical feature. Constant value patterns
are the most easily replaceable by if/elif part of PEP 622.
- I’m sure the PEP authors have a better understanding than I of what use
cases come up in practice; the fact that they didn’t address this is maybe
revealing.
- A discussion of allowing expressions in constant value patterns is a
slight digression from alternative syntax for constant value patterns and I
don’t want to go too deep down the rabbit hole and lose sight of the
original question.

I think it could be very reasonable to want to use dictionary lookups,
especially since a lot of older code / libraries use dicts for enum-like
use cases.

And arithmetic expressions (outside of powers of 2 and 10):
```
match unit_value:
case %(7 * 24 * 60 * 60): return “week”
...
```
And function calls:
```
match hsv_color:
case %(hsv(“black”)): ...
case %(hsv(“cyan”)): ...
case (_, 0, _): return “some sort of grey”

match git_bisect_action:
case %(config.get_old_term()): ...
case %(config.get_new_term()): ...

match conn:
case %(get_current_conn()): ...
case Connection(host, port): ...
```

The caveats above apply, and even if you find the above examples
compelling, this would probably fall in the 10 bucket of 90/10 usage. But
if our syntax for constant value patterns made it natural / easy to
support, it’s something to consider, either now or later a la PEP 614.

On Sat, 4 Jul 2020 at 19:15, Chris Angelico  wrote:

> On Sun, Jul 5, 2020 at 12:03 PM Shantanu Jain 
> wrote:
> > - Finally, I did mention increasing the scope of constant value patterns
> to accommodate expressions (as opposed to just dotted names). If we were to
> do this, it’s a reason to prefer some syntaxes for constant value patterns
> over others.
> >
>
> I'm kinda theoretically in favour of expressions, but only the sort
> that logically "feel" like constants. Unary minus and the addition of
> real and imaginary parts are already supported, so what's still of
> value? IMO exponentiation of 2 is usually better spelled in hex
> (instead of 2**10, use 0x400, unless there's good reason), and since
> you can have underscores to break up an integer, that handles powers
> of 10 as well. What notations would you want to use?
>
> ChrisA
> ___
> Python-Dev mailing list -- python-dev@python.org
> To unsubscribe send an email to python-dev-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/T24W2FZ6UY36CI2GP4LKGBSLSHBYH4K3/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/YFGOGWIKXWT3REL335WOR4ZTQMJC7SXL/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 622: Structural Pattern Matching

2020-07-04 Thread Chris Angelico

On Sun, Jul 5, 2020 at 12:03 PM Shantanu Jain  wrote:
> - Finally, I did mention increasing the scope of constant value patterns to 
> accommodate expressions (as opposed to just dotted names). If we were to do 
> this, it’s a reason to prefer some syntaxes for constant value patterns over 
> others.
>

I'm kinda theoretically in favour of expressions, but only the sort
that logically "feel" like constants. Unary minus and the addition of
real and imaginary parts are already supported, so what's still of
value? IMO exponentiation of 2 is usually better spelled in hex
(instead of 2**10, use 0x400, unless there's good reason), and since
you can have underscores to break up an integer, that handles powers
of 10 as well. What notations would you want to use?

ChrisA
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/T24W2FZ6UY36CI2GP4LKGBSLSHBYH4K3/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 622: Structural Pattern Matching

Apologies if I misunderstand anything, but my suggestion was just an
alternative to the dot syntax for constant value patterns (which along with
literal patterns are how PEP 622’s proposes to to cover the “more flexible
switch” use case).

This syntax is more verbose than PEP 622’s dot syntax for identifying
constant value patterns, but that’s the intention. A number of messages in
the thread point out that the difference between `case FOO: …` and `case
.FOO: …` is very easy to miss.

There are a couple other proposals for how to identify constant value
patterns (and proposals for having constant value patterns be the default
and capture patterns be the ones explicitly demarcated).
The one suggested the most is `case $FOO: …`. This is less verbose than my
suggestion, but a) it requires introducing a new symbol to Python, b) it
doesn’t correspond to any existing Python syntax, whereas syntax that’s
reminiscent of format strings might build on a shared substitution metaphor
in users’ minds.

The last two lines of my suggestion were just pointing out another
potential reason to prefer this bikeshed over dot syntax (and others
proposed at
https://github.com/python/peps/blob/master/pep-0622.rst#alternatives-for-constant-value-pattern
): if we wanted to extend constant value patterns to match constant
expressions (as opposed to just dotted names), having syntax that uses
delimiters might be more readable than a dot or dollar prefix — at least to
me it’s easier to parse a delimited region to see what part of a pattern
would be matched against literally.

tldr;
- My suggestion was explicitly just bikeshedding syntax for constant value
patterns (the “slightly more flexible switch” part of PEP 622).
- The relative verbosity as compared to dot prefix syntax is meant as a
feature, since it’s very easy to miss the dot
- If you’re a proponent of dot syntax, you won’t see any value in this
suggestion. Given that dot syntax seemed to come up in the thread a fair
amount, and that the PEP calls it the “trickiest item”, I thought it might
be worth suggesting some other options.
- Finally, I did mention increasing the scope of constant value patterns to
accommodate expressions (as opposed to just dotted names). If we were to do
this, it’s a reason to prefer some syntaxes for constant value patterns
over others.

On Sat, 4 Jul 2020 at 16:51, Emily Bowman  wrote:

> I don't see how this extrapolates to arbitrary, extended match
> expressions? You're proposing a slightly more flexible switch, which match
> is only intended to be as the most basic case. Even if you purely swapped
> it out with any the various proposals for identifying a constant vs a
> target, it's still far more verbose than any of them.
>
> On Sat, Jul 4, 2020 at 4:31 PM Shantanu Jain 
> wrote:
>
>> Thank you for this PEP! Pattern matching is really exciting.
>>
>> As the PEP mentions and the thread evidences, the current dot syntax for
>> the “constant value pattern” is a tricky point. Given this, I thought I’d
>> throw another suggestion into the bikeshed.
>>
>> Use percent placeholder to indicate lookup (or even eval) semantics for a
>> given name. For example:
>> ```
>> FOO = 1
>> value = 0
>>
>> match value:
>> case %(FOO):  # This would not be matched
>> ...
>> case BAR:# This would be matched
>> ...
>> ```
>> I like this syntax because it’s reminiscent of named substitution in
>> percent formatted strings. It suggests a substitution / placeholder
>> metaphor that is quite fitting. It has the benefit of not introducing a new
>> symbol into Python and being explicit and hard to miss, including in nested
>> contexts.
>>
>> Note, it seems like it would also be technically possible to use curly
>> braces (the more idiomatic means of named substitution in Python 3):
>> ```
>> case {FOO}: …
>> ```
>> The main downside of this is that it could look like some sort of
>> singleton “set pattern” (note that the PEP only supports “sequence
>> patterns” and “mapping patterns”).
>> (But set patterns maybe don’t quite make sense + if your set pattern had
>> multiple elements you’d still get a SyntaxError. For other examples where
>> something in Python looks like a set literal but isn’t, refer to `{}` and
>> f-strings, so it’s maybe not the biggest stretch)
>>
>> Both of these suggestions could also allow us more flexibility for
>> constant value patterns, since currently there isn't a good way to match
>> against a constant expression. For example, we could extend this syntax to
>> allow us to express:
>> ```
>> case %(2 ** 10): ...
>> ```
>> ___
>> Python-Dev mailing list -- python-dev@python.org
>> To unsubscribe send an email to python-dev-le...@python.org
>> https://mail.python.org/mailman3/lists/python-dev.python.org/
>> Message archived at
>> https://mail.python.org/archives/list/python-dev@python.org/message/YQUCFREQ2P7NENOTPBE277I3BZ6DGXSR/
>> Code of Conduct:

[Python-Dev] Re: [Suspected Spam]Re: Recent PEP-8 change

2020-07-04 Thread Emily Bowman

On Sat, Jul 4, 2020 at 5:37 PM Greg Ewing 
wrote:

> On 5/07/20 3:24 am, Stephen J. Turnbull wrote:
> > Amusingly, Strunk (1918) was perfectly happy with split infinitives,
> > though he noted it centered whiteness.  (Obviously he didn't put it
> > that way, more along the lines of "some people will look down on
> > you.")
>
> Um... what?
>
> Are you saying that people who split infinitives are usually
> black, and the people who look down on them are white? If so,
> it would seem that Strunk is actually standing up for black
> people here.
>
> (I don't actually believe this has anything to do with race,
> I'm just trying *to fully understand* your reasoning.)
>

Whatever he meant, nothing about split infinitives is in my 1918 original
copy of Strunk's rules, which is basically a compilation of common-sense
ways to not write like a legal paper or dissertation trying to baffle the
reviewers into approval. Which, sadly, continues into this day.

-Em
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/X4RPPBRSTIS3D4IEE3NUI7BN6465YFFP/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: [Suspected Spam]Re: Recent PEP-8 change


On 5/07/20 3:24 am, Stephen J. Turnbull wrote:

Amusingly, Strunk (1918) was perfectly happy with split infinitives,
though he noted it centered whiteness.  (Obviously he didn't put it
that way, more along the lines of "some people will look down on
you.")


Um... what?

Are you saying that people who split infinitives are usually
black, and the people who look down on them are white? If so,
it would seem that Strunk is actually standing up for black
people here.

(I don't actually believe this has anything to do with race,
I'm just trying *to fully understand* your reasoning.)

--
Greg
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/F7ZMCXE3T7A5QDC5DOFTLMYF7SW4J2TK/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: [Python-ideas] Re: Amend PEP-8 to require clear, understandable comments instead of Strunk & White Standard English comments


On 5/07/20 8:30 am, MRAB wrote:

On 2020-07-04 21:07, Martin Dengler wrote:

How do you spell "regionalism"?

As far as I'm aware, there's only one way to spell it,


I suppose there could be some planet where it's spelled
"regionalizm".

--
Greg
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/A72EKYZW27YWFC3CDIIBB3DJXT5HFHJJ/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Recent PEP-8 change


On 5/07/20 8:23 am, MRAB wrote:

On 2020-07-04 19:23, Paul Moore wrote:

Surely the obvious thing to do would be to use Monty Python characters?

True, but if they were all called Eric it could be confusing.


Also the Monty Python team were all white, so it wouldn't
really solve the problem.

--
Greg
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/ZDUWTKFQAGW5YSQPXXWWYBPHKSU55FJP/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 622: Structural Pattern Matching

2020-07-04 Thread Emily Bowman

 I don't see how this extrapolates to arbitrary, extended match
expressions? You're proposing a slightly more flexible switch, which match
is only intended to be as the most basic case. Even if you purely swapped
it out with any the various proposals for identifying a constant vs a
target, it's still far more verbose than any of them.

On Sat, Jul 4, 2020 at 4:31 PM Shantanu Jain  wrote:

> Thank you for this PEP! Pattern matching is really exciting.
>
> As the PEP mentions and the thread evidences, the current dot syntax for
> the “constant value pattern” is a tricky point. Given this, I thought I’d
> throw another suggestion into the bikeshed.
>
> Use percent placeholder to indicate lookup (or even eval) semantics for a
> given name. For example:
> ```
> FOO = 1
> value = 0
>
> match value:
> case %(FOO):  # This would not be matched
> ...
> case BAR:# This would be matched
> ...
> ```
> I like this syntax because it’s reminiscent of named substitution in
> percent formatted strings. It suggests a substitution / placeholder
> metaphor that is quite fitting. It has the benefit of not introducing a new
> symbol into Python and being explicit and hard to miss, including in nested
> contexts.
>
> Note, it seems like it would also be technically possible to use curly
> braces (the more idiomatic means of named substitution in Python 3):
> ```
> case {FOO}: …
> ```
> The main downside of this is that it could look like some sort of
> singleton “set pattern” (note that the PEP only supports “sequence
> patterns” and “mapping patterns”).
> (But set patterns maybe don’t quite make sense + if your set pattern had
> multiple elements you’d still get a SyntaxError. For other examples where
> something in Python looks like a set literal but isn’t, refer to `{}` and
> f-strings, so it’s maybe not the biggest stretch)
>
> Both of these suggestions could also allow us more flexibility for
> constant value patterns, since currently there isn't a good way to match
> against a constant expression. For example, we could extend this syntax to
> allow us to express:
> ```
> case %(2 ** 10): ...
> ```
> ___
> Python-Dev mailing list -- python-dev@python.org
> To unsubscribe send an email to python-dev-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/YQUCFREQ2P7NENOTPBE277I3BZ6DGXSR/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/WTUD5LSX7QZVSJM4UZLAVLW5OV4PNWS2/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 622: Structural Pattern Matching

Thank you for this PEP! Pattern matching is really exciting.

As the PEP mentions and the thread evidences, the current dot syntax for
the “constant value pattern” is a tricky point. Given this, I thought I’d
throw another suggestion into the bikeshed.

Use percent placeholder to indicate lookup (or even eval) semantics for a
given name. For example:
```
FOO = 1
value = 0

match value:
case %(FOO): # This would not be matched
...
case BAR:# This would be matched
...
```
I like this syntax because it’s reminiscent of named substitution in
percent formatted strings. It suggests a substitution / placeholder
metaphor that is quite fitting. It has the benefit of not introducing a new
symbol into Python and being explicit and hard to miss, including in nested
contexts.

Note, it seems like it would also be technically possible to use curly
braces (the more idiomatic means of named substitution in Python 3):
```
case {FOO}: …
```
The main downside of this is that it could look like some sort of singleton
“set pattern” (note that the PEP only supports “sequence patterns” and
“mapping patterns”).
(But set patterns maybe don’t quite make sense + if your set pattern had
multiple elements you’d still get a SyntaxError. For other examples where
something in Python looks like a set literal but isn’t, refer to `{}` and
f-strings, so it’s maybe not the biggest stretch)

Both of these suggestions could also allow us more flexibility for constant
value patterns, since currently there isn't a good way to match against a
constant expression. For example, we could extend this syntax to allow us
to express:
```
case %(2 ** 10): ...
# or
case {get_default()}: ...
```
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at
https://mail.python.org/archives/list/python-dev@python.org/message/Y4I4PO3VFRYAJUAW2JXA4IYVN7NZMTDQ/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: PEP 622: Structural Pattern Matching

Thank you for this PEP! Pattern matching is really exciting.

As the PEP mentions and the thread evidences, the current dot syntax for
the “constant value pattern” is a tricky point. Given this, I thought I’d
throw another suggestion into the bikeshed.

Use percent placeholder to indicate lookup (or even eval) semantics for a
given name. For example:
```
FOO = 1
value = 0

Both of these suggestions could also allow us more flexibility for constant
value patterns, since currently there isn't a good way to match against a
constant expression. For example, we could extend this syntax to allow us
to express:
```
case %(2 ** 10): ...
```
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at
https://mail.python.org/archives/list/python-dev@python.org/message/YQUCFREQ2P7NENOTPBE277I3BZ6DGXSR/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Recent PEP-8 change


On 5/07/20 3:26 am, Stephen J. Turnbull wrote:

Greg Ewing writes:
  > Maybe we should use randomly generated names for hypothetical
  > persons?

Randomly generated according to what character repertoire and lexical
rules (I'm not talking about British v. American)?


Randomly selected ones!

--
Greg
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/PHUUN7FCG5M5TXKKUPEBGCA3EAJAXEX7/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: [Python-ideas] Re: Amend PEP-8 to require clear, understandable comments instead of Strunk & White Standard English comments


On 2020-07-04 21:07, Martin Dengler wrote:

On Sat, Jul 04, 2020 at 05:51:04PM +0100, MRAB wrote:
>I'd also add: Try to avoid regionalisms; aim for a 
>broadly "international" form of the language. Some 


How do you spell "regionalism"?

Martin

PS: Irony intended


As far as I'm aware, there's only one way to spell it, but I'm sure 
someone can phrase it better.


___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/7A4AWOEAWU4ZZBPSJ67C5BP3BYA6RRZG/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Recent PEP-8 change

On 2020-07-04 19:23, Paul Moore wrote:

On Sat, 4 Jul 2020 at 17:48, MRAB  wrote:
>
> On 2020-07-04 05:51, Greg Ewing wrote:
> > On 4/07/20 4:33 am, Jim J. Jewett wrote:
> >> If Bob and Alice seem neutral to you, would you do a double-take on 
Kehinde or Oladotun?
> >
> > Maybe we should use randomly generated names for hypothetical persons?
> >
> Ideally they should be short names, one or two syllables.

Surely the obvious thing to do would be to use Monty Python characters?

True, but if they were all called Eric it could be confusing.
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/ZYK5PHZUYA2PUVWJSZUS52R6AOJLPS7L/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: [Python-ideas] Re: Amend PEP-8 to require clear, understandable comments instead of Strunk & White Standard English comments

2020-07-04 Thread Martin Dengler


On Sat, Jul 04, 2020 at 05:51:04PM +0100, MRAB wrote:
I'd also add: Try to avoid regionalisms; aim for a 
broadly "international" form of the language. Some 


How do you spell "regionalism"?

Martin

PS: Irony intended
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/3L7UEATIHJ4JV5UDXLMKRUMC3H2EXWLY/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Recent PEP-8 change

2020-07-04 Thread Paul Moore

On Sat, 4 Jul 2020 at 17:48, MRAB  wrote:
>
> On 2020-07-04 05:51, Greg Ewing wrote:
> > On 4/07/20 4:33 am, Jim J. Jewett wrote:
> >> If Bob and Alice seem neutral to you, would you do a double-take on 
> >> Kehinde or Oladotun?
> >
> > Maybe we should use randomly generated names for hypothetical persons?
> >
> Ideally they should be short names, one or two syllables.

Surely the obvious thing to do would be to use Monty Python characters?
Paul
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/SQ66KMU3ABY5KN4OHDX22HPUIIRFDLDO/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: [Python-ideas] Re: Amend PEP-8 to require clear, understandable comments instead of Strunk & White Standard English comments

On 2020-07-04 16:23, Stephen J. Turnbull wrote:

@Inada-sama: For RFC conformance to S, see footnote [3] at the end.

MRAB writes:

> If you believe you have something important to say, then at least
> say it clearly.

Indeed -- that commit log is an example of the kind of writing the
reference to Strunk & White was intended to reduce; repetitive,
jargon-filled, and mostly unnecessary to make the point.[1] Ironic,
but not the only irony to be found in this commit.

Because I have seen the deterrent effect in action -- *it is real* --
I'd be sympathetic to this change if I hadn't directly experienced the
value of a rule set like that in Strunk & White in teaching non-native
speakers about writing English for technical purposes. Since I
believe an admonition to "write clear and easily understandable
English" is a deterrent too, especially for non-natives, I would
prefer deleting the whole thing to this change, though.

The claim is that requiring Strunk & White deters PoC. I believe it.
But by discarding all rules, this change "centers" English-speakers at
the expense of the needs of large populations of *non-native-speaking*
PoC. Many non-natives would benefit from adopting some of the advice
in Strunk & White for *writing* clearly, and if others follow that
advice, it would easier for them to *read*.[2] Don't take my word for
it: Naoki Inada testifies to both issues in his post about "RFC
English".[3]

It has also been claimed that many neuro-atypical folks find detailed
rules comforting, as opposed to broad admonitions of that kind. Seems
plausible, but I can't speak to it from personal experience or
testimony of acquaintances. But if so, removing all reference to
concrete rules for clear writing harms and deters them, too.

But "practice what you preach" is a fallacy, I guess. "Do what I say,
not what I do" is the way of the world. Given human fallibility,
maybe this is a not-bad thing, to focus on the merits of folks' speech
rather than the demerits of their actions *shrug*

As I see it, in order of importance, we could say the following about
comments in Python:

1. Comments should not say anything that a programmer with some
experience can read directly from the code, taken out of the
larger context. That eliminates a lot of problematic text right
off the bat! :-)

2. Write comments in English. It is the lingua franca [sic!] of
programming, for better or worse, and Python development is an
international community of programmers. (The language may change,
see "sic!" above. Boy, would I enjoy watching some folks struggle
with Hindi or Chinese.)

3. Write in a comfortable dialect[4]. (Exceptions: legalese and
The Academic Register are strictly forbidden, even if you're
native in one of those. :-)
I'd also add: Try to avoid regionalisms; aim for a broadly
"international" form of the language. Some words and phrases might be
specific to a certain region, or have different, possibly conflicting,
meanings elsewhere.

4. Write clear and easily understandable comments, remembering that
many potential readers are not native speakers, let alone native
in "Standard" English.

5. For advice on writing clearly, Zinsser is a good textbook on
writing to communicate. Strunk & White is a concise collection of
concrete rules with examples of usage that help many to write more
clearly, and its table of contents serves as a somewhat Petersian
"Zen of Technical Writing". (There may be better alternatives to
both for those purposes, but I don't know of any.)

[snip]

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at
https://mail.python.org/archives/list/python-dev@python.org/message/HOLPBECIPKDDIXZEISB7VLJIUUPGD7O3/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Recent PEP-8 change