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