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

[Steven D'Aprano]

On Wed, Jan 30, 2019 at 03:51:22PM -0600, Abe Dillon wrote:
> [Steven D'Aprano]
> 
> > > ALL_CAPS_IS_OBNOXIOUS
> > >
> > > It destroys the visual flow of code
> > Does it? This claim doesn't ring true to me. To me, "visual flow of
> > code" is the way it flows down and across the page, not the shape of the
> > individual words.
> 
> 
> It does. Your field of vision is two-dimensional and multi-scale.
> Your visual system uses lots of queues to determine what to focus on and
> how to interpret it.
> So both the way code flows down the page and the shape of individual words
> matter to readability:

I'm not disputing that, I'm disputing your claim that the presence of a 
all-caps CONSTANT somewhere on a page full of lower and mixed case code 
"destroys the visual flow of code".

The rest of your comment is a distraction. You have made one strong 
claim (all-caps constants destroy the flow of code), I've explained why 
I consider it dubious, and you've introduced a completely different, 
milder, uncontroversial fact, that the shape of individual words 
slightly influences how that word is read.

Yes they do. How does that support your claim that a handful of all-caps 
names scattered over a page of code "destroys the flow of text"? Does 
the same apply to a page of prose that happens to mention NASA, the 
USSR, the USA, FAQ or some other TLA?

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

Let's start with the first paragraph:

    "There's nothing worse than browsing the web and being 
    hit with a huge slab of text in All Caps - that is, all 
    in CAPITAL LETTERS."

Yes there is: websites (like this one) which use low-contrast light 
grey text on a white or slightly-lighter grey background, especially if 
(like this one) they use a sans serif font.

(It could have been even worse though: at least the page doesn't use a 
tiny font size.)

What does the shape of the letters matter if the reader has problems 
distinguishing them from the background due to lack of contrast?

https://www.contrastrebellion.com/


In any case, we're not talking about "a huge slab" of all-caps. If you 
write your Python code like this:

    # Don't do this!
    import MYMODULE
    SOME_VARIABLE = 1234
    for MYLOOPVARIABLE in MYMODULE.SEQUENCE(SOME_VARIABLE):
        PROCESS(MYLOOPVARIABLE)
        if SOME_CONDITION(MYLOOPVARIABLE) or FLAG:
            with SOMETHING as ANOTHER:
                 DO_ANOTHER_THING_WITH(ANOTHER)

then this argument about large blocks of all-caps is relevant. Nobody 
here is advocating for great slabs of all-caps, and neither does PEP 8. 
For individual words occasionally scattered around the code, the 
argument against using nothing but all-caps is irrelevant.

    When we read, we don't actually look at every letter in a sentence,
    but actually the shapes of the words.

That's an over-simplification, i.e. inaccurate. But certainly looking at 
the overall shape of words is *part* of what we do. However, if it was 
*all* we do when reading, then we couldn't tell these words apart:

    case more core mean even user

    then when this that else than 

If I remember correctly, didn't you make the claim earlier that all-caps 
names draw the eye and emphasize that word?

(If you did, I agree with it, and acknowledge that this in and of itself 
is not a desirable thing. It is a cost worth paying for the other 
benefits of having a convention for all-caps which doesn't depend on 
using a smart IDE and syntax highlighting.)

It strikes me as a bit strange that one moment you are (?) claiming that 
all-caps names draw the eye, and the next you are giving as evidence for 
your position a source which claims the opposite:

    "...the monotonous rectangular shape of the All Caps text reducing 
    the emphasis on the All Caps word."

Seems like you are cherry-picking arguments that support you and hoping 
we don't read all the way through the article to find those that go 
against you. Speaking of which:

    "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."

We can add to that, from a coding perspective, all-caps can be useful 
for constants, environment variables, and other uses which don't involve 
reading large blocks of all-caps.


[...]
> > I can immediately tell that unlike spam and eggs, FILENAME ought to be a
> > global constant, which is a valuable hint that I can probably find the
> > value of FILENAME by looking at the top of the module, and not worry
> > about it being rebound anywhere else.
> 
> 
> <control> + f  "filename ="
> You can tell if its rebound anywhere by the number of matches.

Can I? You seem to know a lot about the editor I am using. What if it 
doesn't show the number of matches but only one match at a time?

You are assuming that I only have one global variable filename and no 
local variables using the same name. That's an unsafe assumption.

But even if it were safe, it seems strange that you are so worried about 
the microsecond or so extra reading time it takes to recognise an 
all-caps word, based on the "shape of the word" model, yet are prepared 
to pay this enormous cost probably counted in multiple seconds:

- change the focus of my attention from the code I'm reading

- remember this unreliable trick (see above)

- move my hands to the position to type Ctrl-F

- which for touch-typists involves the hardest key on the keyboard
  to press (Ctrl) using the weakest finger on the hand

- depending on the editor, I may have to pause a moment or two 
  while the search occurs

- or possibly I have to de-focus and ignore intermediate results 
  if the search occurs while I'm typing

- refocus on where the number of results are displayed

- correctly interpret this number in terms of the semantics
  "one match means only one binding"

- draw the correct conclusion "hence a constant"

- worry about whether I missed some other way the variable might
  have been re-bound e.g. ``for filename in list_of_files``

- and finally refocus back to where I'm reading the code.

And this is supposed to be an improvement over a clean convention for 
constants? I don't think so.



> [Steven D'Aprano]
> 
> > What naming convention would you suggest for distinguishing between
> > constants and variables?
> 
> None. You don't need one.

You are correct, having a good naming convention for constants is not 
strictly necessary. Especially for those who don't care about the 
readability of their code.

No naming convention is *necessary*, so long as the variable names are 
distinguishable by the interpreter we don't need conventions to 
distinguish functions from variables from classes from constants. We 
could just name everything using consecutive x1, x2, x3 ... names and 
the code would run just as well.

Having good naming conventions is very valuable, but not *necessary*. 
Using all-caps for constants is very valuable, but you are right, it 
isn't *necessary*. 


> [Steven D'Aprano]
> 
> > We can (usually) accurately
> > recognise modules, classes and functions from context, but we can't do
> > the same for constants.
> 
> 
> What are you basing that claim on? I can tell that  math.pi, string.digits,
> and timedelta.resolution are constants just fine.

Sure, but only because you know the semantics that pi is a numeric 
constant, digits refers only to the Hindi-Arabic numerals 0...9, etc. I 
wouldn't have guessed that timedelta.resolution is a constant, because I 
don't know that module so well.

But how about

    filename
    pattern
    location
    person
    sigma
    characters

Which of those are constants?

All of those are taken from real code I've written, except "characters" 
which I just made up. All of them have been constants in some modules 
and variables in others, except for sigma, but I'm not telling you which 
it was. Since it is so easy for you to tell a constant from a variable, 
you ought to be able to tell which it was. Right?

Remember, the person reading your code is not necessarily an expert in 
the domain of your code. It might be trivial for you to say that 
spam.aardvark cannot possibly be anything but a constant, but to those 
who aren't experts in the domain, they might as well be metasyntactic 
variables.


-- 
Steve