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 was to me when I encountered the book in 1971 or so,
and later additions have taken their place beside it as they appeared.
I wouldn't object to
When writing English, write clearly and understandably. Consider
your audience -- many readers of your comments in Python sources
will be non-native speakers. "The Elements of Style" by Strunk
and White provides a set of guidelines some consider useful in
writing clearly and understandably.
Steve Barnes suggestion of referring to community standards might be
good too. I was peripherally involved in a situation that involved
removing all references to "brain damage" from a medium size code base
once. OTOH, I doubt that phrase would pass review in Python, ever.
David Mertz points out that all of the rules in Strunk and White
require subjective decisions. It's true that in any writing (even Mad
Libs), eventually all decisions are subjective. However, "clear and
understandable" is an aggregated level of subjectivity, while the
individual principles (there are about 40 of them) in Strunk and White
may be easier to grasp for most people. They certainly were for me.
Whether that third sentence in my suggested wording is appropriate for
PEP 8 is not my decision. But 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.
Steve
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@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/HACZ4KGKSOAZENAVBJ6IR4HRPL57QREO/
Code of Conduct: http://python.org/psf/codeofconduct/
