[Python-ideas] AMEND PEP-8 TO DISCOURAGE ALL CAPS
Abe Dillon
abedillon at gmail.com
Wed Jan 30 20:57:35 EST 2019
[Steven D'Aprano]
> I'm not disputing that,
I mean, you literally wrote:
[Steven D'Aprano]
> To me, "visual flow of code" is the way it flows down and across the
> page, *not* the shape of the
> individual words.
So it sounded a lot like you were.
[Steven D'Aprano]
> 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".
Maybe I was being a little hyperbolic, but it depends on degree. If every
other line of code has LOGGER.debug(...) or STATSD_EMITER.count(...) in it,
then it tends to out-shout the code you're trying to read.
[Steven D'Aprano]
> The rest of your comment is a distraction.
Like going on a rant about one of my sources contrast ratios and font
choices?
[Steven D'Aprano]
> 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.
I'm sure you've heard of "Typoglycemia
<https://en.wikipedia.org/wiki/Typoglycemia>" before. It would be
interesting to see how readability degrades as more and more of the
scrambled words are converted to all caps.
[Steven D'Aprano]
> 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
I guess I might have some sort of disability that you don't but I find
those two lines much more difficult to read or even focus on than normal
text. It's very hard to describe the sensation, but it's very unpleasant.
It's like my eye doesn't know where to start so I keep scanning back and
forth like a Cylon <https://imgur.com/gallery/cF5Dlhp>.
[Steven D'Aprano]
> If I remember correctly, didn't you make the claim earlier that all-caps
> names draw the eye and emphasize that word?
Yes. It was I who said that. I know it seemingly contradicts statements in
some of the sources I cited, but I think in those cases are referring to
"slabs" of all caps. When it's lots of normal text with a few all caps, my
eye is drawn to the all caps; when it's a block of all caps, everything is
a wash and perhaps the few lower-case words stand out.
I'm sorry that's confusing. I might go look for better sources that pertain
more exclusively to code, but honestly; it doesn't look like anyone else
cares or will agree with me any time soon.
[Steven D'Aprano]
> It seems strange that you are so worried about
> the microsecond or so extra reading time it takes to recognize 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: ...
It seems like the fundamental problem you have is trying to find where and
when a variable was last bound.
I don't understand why your go-to solution to that problem is in the
style-guide of a language. It doesn't seem at all
related to style. It seems like the kind of problem that's completely in
the wheel-house of an IDE. Does it not feel to you
like you're relying on a style-kludge to make up for inadequate tools?
Why perpetuate that? Why not demand more from your tools?
[Steven D'Aprano]
> 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.
I've pointed this out several times before, but Python itself violates the
all caps constant naming convention all over the place and yet,
hardly anybody notices. The fear you seem to have about not communicating
constancy clearly seems to be entirely hypothetical. The only
person that's tried to show me a case where using all caps was crucial
completely defeated his own argument by presenting a non-constant
that had to be documented because its usage was so non-obvious.
I haven't heard an explanation yet for why it's so important that
pickle.DEFAULT_PROTOCOL be all caps while sys.copyright is not.
If it's as important as you claim, then shouldn't there be mass hysteria?
Cats and dogs getting along together, etc.?
[Steven D'Aprano]
> 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.
Be honest: what would your first guess be if you saw code using
timedelta.resolution?
Where and when would you guess it was last bound?
Would you guess that it's a variable that changes on a whim or is often
rebound?
How often do you deal with interfaces where module-level variables are
intended to be re-bound?
Would you say that's good practice?
[Steven D'Aprano]
> 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?
I would be able to tell very quickly if I saw those in my IDE whether they
were local or global variables.
I tend to only import up to the module level (as per Google's style
guidelines) specifically so that others know
where various variables (like math.pi) come from.
In my experience, most constants are configuration that people haven't
decided to make configurable yet.
I worked at a computer vision lab where the camera had a resolution of 640
x 480 which were originally represented as
constants in a lot of our code VERTICAL_RESOLUTION and HORIZONTAL_RESOLUTION
,
eventually; they became self.horizontal_resolution and
self.vertical_resolution. So, my guess is that sigma is either a variable
or will become a variable at some point in the future.
On Wed, Jan 30, 2019 at 5:59 PM Steven D'Aprano <steve at pearwood.info> wrote:
> 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
> _______________________________________________
> Python-ideas mailing list
> Python-ideas at python.org
> https://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20190130/a3f3d885/attachment-0001.html>
More information about the Python-ideas
mailing list