[Python-ideas] AMEND PEP-8 TO DISCOURAGE ALL CAPS

[Cameron Simpson]

On 30Jan2019 15:22, Abe Dillon <abedillon at gmail.com> wrote:
>> Capitalizing constants may be slightly harder to read but constants in
>code are the minority and emphasizing them is precisely the point.
>
>The question I'm trying to get everyone to actually think about:
>
>Is the communication of constancy via ALL CAPS so important that it must be
>in PEP-8 despite the documented harm that all caps does to readability?

Lots of caps is an issue. Using all caps for specific low frequency 
items is a much smaller issue, and having "constants" visually 
distinctive is a handy thing. And constants are not just "things that 
should not be changed", such as a variable from an outer scope. They 
tend to be default values and genuine constants (such as equivalence 
values form another API, as in the socket examples).

Your cited URLs are almost all about prose in all caps - whole sentences 
and paragraphs in all caps. Wikipedia aside, they _all_ have carve outs 
for places where all caps can be valuable:

>https://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so-hard-to-read

"From a design perspective, All Caps can be useful for labels, logos and 
menus where your message doesn't involve reading large sections of 
text."

>https://en.wikipedia.org/wiki/All_caps#Readability
>https://uxmovement.com/content/all-caps-hard-for-users-to-read/

"When is it okay to use all caps? All caps are fine in contexts that 
don’t involve much reading, such as logos, headings, acronyms, and 
abbreviations."

>https://practicaltypography.com/all-caps.html

"That doesn’t mean you shouldn’t use caps. Just use them judiciously.  
Caps are suitable for headings shorter than one line (e.g., “Table of 
Contents”), headers, footers, captions, or other labels. Caps work at 
small point sizes. Caps work well on letterhead and business cards."

>I've gotten many responses that seem like a knee-jerk reaction in favor of
>the status quo. I get the sense people "like" all caps because they've been
>conditioned to believe it conveys important information, but they haven't
>taken the time to really consider how valid that belief is.

You may find that (a) plenty of us have been using this convention for a 
very long time and (b) we find it useful and (c) it doesn't cause us any 
trouble. Also, cross language conventions have additional value. Don't 
think we've never thought about its value.

>Consider that math.pi and math.e are constants that are not all caps, have
>you ever been tempted to re-bind those variables?

No, but "e" and "pi" are _conventionally_ spelt in lowercase in prose.  
Which is why they are lower case in the math module. As with the socket 
example below, here they match their casing in their source context 
(mathematics).

And regarding temptation to change these, there's a very old humorous 
anecdote about FORTRAN, in that like Python it has no constants: you can 
change "PI", for example to 3. Badness ensues. Nobody is arguing that we 
should consider math.e or math.pi sane things to modify because the 
Python module uses lower case for their names.

>Do you seriously worry
>that those variables are going to be re-bound by other code? Functions and
>classes are essentially constants that aren't all caps, yet nobody gets
>confused about whether or not to re-bind those, or if other code will
>rebind them.

You'll notethat in Python, assigning to a name in a function _causes_ 
that name to be locally scoped. This avoids a whole suite of accidents.

And we rebind names bound to functions all the time, not just for monkey 
patching but also when we pass functions as callbacks. Python function 
names are _not_ functions, they're _references_ to functions.

>If socket.AF_INET6 were socket.af_inet6 would you consider re-binding that
>variable? Would you be worried that other code will re-bind it? Can you
>measure the value of the information conveyed by all-caps? Are you so sure
>that it's as important as you think?

It is important for 2 reasons: it adhere's to the well established 
convention of a constant being in all caps, which has value in itself 
(adherence to the convention) _and_ it is spelled exactly like the 
AF_INET6 constant from the C socket API, of which Python's socket module 
is essentially a shim with some additional utility facilities.

>I've gotten a lot of responses like, "If you don't like it just ignore
>PEP-8, it's not mandatory".
>A) It is mandatory in many cases.
>B) We could just as easily NOT prescribe all caps in PEP-8 but still allow
>it. In other words: you can use all caps if you want to but it's not
>mandatory or in PEP-8. I would like to discourage its use, but we don't
>have to go so far. That way nobody has to violate PEP-8.

Arguing that "nobody has to violate PEP-8" by the mechanism of just 
dropping recommendations from it isn't very sound, IMO.

If your in house style eschews caps for constants, go right ahead.  
Nobody will stop you. PEP-8 is primarily for the stdlib, where like any 
shared body of code it is useful to have common style.

Plenty of places use PEP-8 as a basis - it is reasonable, and it gets 
you a fairly complete style guide from day 1. By all means diverge from 
it on a reasoned basis in your own code or within your own organisation.  
I do in my personal code: primarily 2 space indentation instead of 4, 
and my docstring formatting differs as well.

And correspondingly, feel free to document your reasons for diverging.  
They may be universally valid or domain specific; provide such context.  
But I suspect you'll not get much traction on changing PEP-8 itself in 
this aspect because the convention is widely liked.

Finally, I've worked in ALL CAPS programming environments. BASIC and 
assembler were traditionally written in all caps. Also FORTRAN. Also 
Modula-3, at least for its keywords (IF, etc). On the whole I think the 
world is a better place for being mostly lower case. To such an extent 
that I wrote a preprocessor for all my Modula-3 to transcribe my 
personal lower case programmes to upper case for the compiler.

But the flip side of being in a mostly lower case world is that having 
occasional upper case as a standout formatting for particular entities 
sudden has more value. And that value has been used for constants for a 
long time with, IMO, some benefit.

Cheers,
Cameron Simpson <cs at cskk.id.au>