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]