On 2020-07-04 16:23, Stephen J. Turnbull wrote:
@Inada-sama: For RFC conformance to S&W, 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/
