@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. :-)
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.)
We could probably get 1-4 into two and a half lines, by leaving out
the jokes and rationale. 5 would probably take a couple more lines.
Or we could just delete the whole thing, which is probably more
advisable than laying a burden of clarity and intelligibility we
ourselves could not bear on non-native and non-Standard speakers.
Regards,
Steve
Footnotes:
[1] I'm not sure why. The OP to Python-Ideas was well-written.
[2] Reading is easier partly because most of the world values
Standard[sic] (American) English or standard (British) English above
other dialects, which is clearly a holdover from "centering whiteness".
But also because many of Strunk & White's rules really do encourage
writing clearly without privileging any dialect (or even language -- I
use those rules effectively in writing Japanese, to the extent I can
write effective Japanese ;-).
[3] Yes, Naoki, I'd say RFC English is conformant to Strunk & White,
especially in the important ways. However, RFC English is further
constrained and by conventions like RFC 2119 "Key words for use in
RFCs to indicate requirement levels". Much of the more complex
content is expressed in formal grammars and pseudo-code. So RFC
English not really a fair test of whether Strunk & White would be
useful to programmers. Unfortunately, there's no style guide I know
of for RFC authors we could cite here -- you learn by getting screamed
at on IETF lists. ;-)
[4] Maybe "style" is a better word, though inaccurate and ambiguous
in this context.
_______________________________________________
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/TYNSMARFTAAPYQRBODBVPYZZULL5MBE2/
Code of Conduct: http://python.org/psf/codeofconduct/
