<div dir="ltr"><br><div>[Steven D'Aprano]<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I'm not disputing that,</blockquote><br></div><div>I mean, you literally wrote:<br><br>[Steven D'Aprano]<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span style="color:rgb(80,0,80)">To me, "visual flow of </span><span style="color:rgb(80,0,80)">code" is the way it flows down and across the page, <b>not</b> the shape of the<br></span><span style="color:rgb(80,0,80)">individual words.</span></blockquote><div><br>So it sounded a lot like you were.<br><br>[Steven D'Aprano]<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I'm disputing your claim that the presence of a <br>all-caps CONSTANT somewhere on a page full of lower and mixed case code <br>"destroys the visual flow of code".</blockquote></div><div><br>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.<br><br>[Steven D'Aprano]<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">The rest of your comment is a distraction.</blockquote><div><br>Like going on a rant about one of my sources contrast ratios and font choices?<br><br>[Steven D'Aprano]<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> When we read, we don't actually look at every letter in a sentence,<br> but actually the shapes of the words. </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">That's an over-simplification, i.e. inaccurate.</blockquote><div><br>I'm sure you've heard of "<a href="https://en.wikipedia.org/wiki/Typoglycemia" target="_blank">Typoglycemia</a>" before. It would be interesting to see how readability degrades as more and more of the scrambled words are converted to all caps.</div></div></div><div><br></div><div>[Steven D'Aprano]<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">But certainly looking at the overall shape of words is *part* of what we do. However, if it was <br>*all* we do when reading, then we couldn't tell these words apart:<br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> case more core mean even user<br> then when this that else than </blockquote></div><div><br></div><div>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 <a href="https://imgur.com/gallery/cF5Dlhp" target="_blank">Cylon</a>.<br><br>[Steven D'Aprano]<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">If I remember correctly, didn't you make the claim earlier that all-caps <br>names draw the eye and emphasize that word?</blockquote><div><br>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.<br><br>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.<br><br>[Steven D'Aprano]<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">It seems strange that you are so worried about <br>the microsecond or so extra reading time it takes to recognize an <br>all-caps word, based on the "shape of the word" model, yet are prepared <br>to pay this enormous cost probably counted in multiple seconds: ...</blockquote><div><br>It seems like the fundamental problem you have is trying to find where and when a variable was last bound.<br>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</div></div></div><div>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<br></div><div>like you're relying on a style-kludge to make up for inadequate tools?<br><br>Why perpetuate that? Why not demand more from your tools?<br><br>[Steven D'Aprano]<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">You are correct, having a good naming convention for constants is not <br>strictly necessary. Especially for those who don't care about the <br>readability of their code.</blockquote><br>I've pointed this out several times before, but Python itself violates the all caps constant naming convention all over the place and yet,<br>hardly anybody notices. The fear you seem to have about not communicating constancy clearly seems to be entirely hypothetical. The only</div><div>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</div><div>that had to be documented because its usage was so non-obvious.<br><br>I haven't heard an explanation yet for why it's so important that <font face="monospace, monospace">pickle.DEFAULT_PROTOCOL</font> be all caps while <font face="monospace, monospace">sys.copyright</font> is not.<br><br>If it's as important as you claim, then shouldn't there be mass hysteria? Cats and dogs getting along together, etc.?<br><br>[Steven D'Aprano]<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Sure, but only because you know the semantics that pi is a numeric <br>constant, digits refers only to the Hindi-Arabic numerals 0...9, etc. I <br>wouldn't have guessed that timedelta.resolution is a constant, because I <br>don't know that module so well.</blockquote><div><br>Be honest: what would your first guess be if you saw code using timedelta.resolution?</div><div>Where and when would you guess it was last bound?<br>Would you guess that it's a variable that changes on a whim or is often rebound?<br>How often do you deal with interfaces where module-level variables are intended to be re-bound?<br>Would you say that's good practice?<br><br>[Steven D'Aprano]<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">how about<br> filename<br> pattern<br> location<br> person<br> sigma<br> characters<br>Which of those are constants?<br>All of those are taken from real code I've written, except "characters" <br>which I just made up. All of them have been constants in some modules <br>and variables in others, except for sigma, but I'm not telling you which <br>it was. Since it is so easy for you to tell a constant from a variable, <br>you ought to be able to tell which it was. Right?</blockquote><br>I would be able to tell very quickly if I saw those in my IDE whether they were local or global variables.<br>I tend to only import up to the module level (as per Google's style guidelines) specifically so that others know</div><div>where various variables (like math.pi) come from.<br><br>In my experience, most constants are configuration that people haven't decided to make configurable yet.<br>I worked at a computer vision lab where the camera had a resolution of 640 x 480 which were originally represented as</div><div>constants in a lot of our code <font face="monospace, monospace">VERTICAL_RESOLUTION</font> and <font face="monospace, monospace">HORIZONTAL_RESOLUTION</font>, </div><div>eventually; they became<font face="monospace, monospace"> self.horizontal_resolution</font> and <font face="monospace, monospace">self.vertical_resolution</font>. So, my guess is that sigma is either a variable</div><div>or will become a variable at some point in the future.<br></div></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Jan 30, 2019 at 5:59 PM Steven D'Aprano <<a href="mailto:steve@pearwood.info" target="_blank">steve@pearwood.info</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On Wed, Jan 30, 2019 at 03:51:22PM -0600, Abe Dillon wrote:<br>
> [Steven D'Aprano]<br>
> <br>
> > > ALL_CAPS_IS_OBNOXIOUS<br>
> > ><br>
> > > It destroys the visual flow of code<br>
> > Does it? This claim doesn't ring true to me. To me, "visual flow of<br>
> > code" is the way it flows down and across the page, not the shape of the<br>
> > individual words.<br>
> <br>
> <br>
> It does. Your field of vision is two-dimensional and multi-scale.<br>
> Your visual system uses lots of queues to determine what to focus on and<br>
> how to interpret it.<br>
> So both the way code flows down the page and the shape of individual words<br>
> matter to readability:<br>
<br>
I'm not disputing that, I'm disputing your claim that the presence of a <br>
all-caps CONSTANT somewhere on a page full of lower and mixed case code <br>
"destroys the visual flow of code".<br>
<br>
The rest of your comment is a distraction. You have made one strong <br>
claim (all-caps constants destroy the flow of code), I've explained why <br>
I consider it dubious, and you've introduced a completely different, <br>
milder, uncontroversial fact, that the shape of individual words <br>
slightly influences how that word is read.<br>
<br>
Yes they do. How does that support your claim that a handful of all-caps <br>
names scattered over a page of code "destroys the flow of text"? Does <br>
the same apply to a page of prose that happens to mention NASA, the <br>
USSR, the USA, FAQ or some other TLA?<br>
<br>
<br>
> <a href="https://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so-hard-to-read" rel="noreferrer" target="_blank">https://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so-hard-to-read</a><br>
<br>
Let's start with the first paragraph:<br>
<br>
"There's nothing worse than browsing the web and being <br>
hit with a huge slab of text in All Caps - that is, all <br>
in CAPITAL LETTERS."<br>
<br>
Yes there is: websites (like this one) which use low-contrast light <br>
grey text on a white or slightly-lighter grey background, especially if <br>
(like this one) they use a sans serif font.<br>
<br>
(It could have been even worse though: at least the page doesn't use a <br>
tiny font size.)<br>
<br>
What does the shape of the letters matter if the reader has problems <br>
distinguishing them from the background due to lack of contrast?<br>
<br>
<a href="https://www.contrastrebellion.com/" rel="noreferrer" target="_blank">https://www.contrastrebellion.com/</a><br>
<br>
<br>
In any case, we're not talking about "a huge slab" of all-caps. If you <br>
write your Python code like this:<br>
<br>
# Don't do this!<br>
import MYMODULE<br>
SOME_VARIABLE = 1234<br>
for MYLOOPVARIABLE in MYMODULE.SEQUENCE(SOME_VARIABLE):<br>
PROCESS(MYLOOPVARIABLE)<br>
if SOME_CONDITION(MYLOOPVARIABLE) or FLAG:<br>
with SOMETHING as ANOTHER:<br>
DO_ANOTHER_THING_WITH(ANOTHER)<br>
<br>
then this argument about large blocks of all-caps is relevant. Nobody <br>
here is advocating for great slabs of all-caps, and neither does PEP 8. <br>
For individual words occasionally scattered around the code, the <br>
argument against using nothing but all-caps is irrelevant.<br>
<br>
When we read, we don't actually look at every letter in a sentence,<br>
but actually the shapes of the words.<br>
<br>
That's an over-simplification, i.e. inaccurate. But certainly looking at <br>
the overall shape of words is *part* of what we do. However, if it was <br>
*all* we do when reading, then we couldn't tell these words apart:<br>
<br>
case more core mean even user<br>
<br>
then when this that else than <br>
<br>
If I remember correctly, didn't you make the claim earlier that all-caps <br>
names draw the eye and emphasize that word?<br>
<br>
(If you did, I agree with it, and acknowledge that this in and of itself <br>
is not a desirable thing. It is a cost worth paying for the other <br>
benefits of having a convention for all-caps which doesn't depend on <br>
using a smart IDE and syntax highlighting.)<br>
<br>
It strikes me as a bit strange that one moment you are (?) claiming that <br>
all-caps names draw the eye, and the next you are giving as evidence for <br>
your position a source which claims the opposite:<br>
<br>
"...the monotonous rectangular shape of the All Caps text reducing <br>
the emphasis on the All Caps word."<br>
<br>
Seems like you are cherry-picking arguments that support you and hoping <br>
we don't read all the way through the article to find those that go <br>
against you. Speaking of which:<br>
<br>
"From a design perspective, All Caps can be useful for labels, <br>
logos and menus where your message doesn't involve reading large <br>
sections of text."<br>
<br>
We can add to that, from a coding perspective, all-caps can be useful <br>
for constants, environment variables, and other uses which don't involve <br>
reading large blocks of all-caps.<br>
<br>
<br>
[...]<br>
> > I can immediately tell that unlike spam and eggs, FILENAME ought to be a<br>
> > global constant, which is a valuable hint that I can probably find the<br>
> > value of FILENAME by looking at the top of the module, and not worry<br>
> > about it being rebound anywhere else.<br>
> <br>
> <br>
> <control> + f "filename ="<br>
> You can tell if its rebound anywhere by the number of matches.<br>
<br>
Can I? You seem to know a lot about the editor I am using. What if it <br>
doesn't show the number of matches but only one match at a time?<br>
<br>
You are assuming that I only have one global variable filename and no <br>
local variables using the same name. That's an unsafe assumption.<br>
<br>
But even if it were safe, it seems strange that you are so worried about <br>
the microsecond or so extra reading time it takes to recognise an <br>
all-caps word, based on the "shape of the word" model, yet are prepared <br>
to pay this enormous cost probably counted in multiple seconds:<br>
<br>
- change the focus of my attention from the code I'm reading<br>
<br>
- remember this unreliable trick (see above)<br>
<br>
- move my hands to the position to type Ctrl-F<br>
<br>
- which for touch-typists involves the hardest key on the keyboard<br>
to press (Ctrl) using the weakest finger on the hand<br>
<br>
- depending on the editor, I may have to pause a moment or two <br>
while the search occurs<br>
<br>
- or possibly I have to de-focus and ignore intermediate results <br>
if the search occurs while I'm typing<br>
<br>
- refocus on where the number of results are displayed<br>
<br>
- correctly interpret this number in terms of the semantics<br>
"one match means only one binding"<br>
<br>
- draw the correct conclusion "hence a constant"<br>
<br>
- worry about whether I missed some other way the variable might<br>
have been re-bound e.g. ``for filename in list_of_files``<br>
<br>
- and finally refocus back to where I'm reading the code.<br>
<br>
And this is supposed to be an improvement over a clean convention for <br>
constants? I don't think so.<br>
<br>
<br>
<br>
> [Steven D'Aprano]<br>
> <br>
> > What naming convention would you suggest for distinguishing between<br>
> > constants and variables?<br>
> <br>
> None. You don't need one.<br>
<br>
You are correct, having a good naming convention for constants is not <br>
strictly necessary. Especially for those who don't care about the <br>
readability of their code.<br>
<br>
No naming convention is *necessary*, so long as the variable names are <br>
distinguishable by the interpreter we don't need conventions to <br>
distinguish functions from variables from classes from constants. We <br>
could just name everything using consecutive x1, x2, x3 ... names and <br>
the code would run just as well.<br>
<br>
Having good naming conventions is very valuable, but not *necessary*. <br>
Using all-caps for constants is very valuable, but you are right, it <br>
isn't *necessary*. <br>
<br>
<br>
> [Steven D'Aprano]<br>
> <br>
> > We can (usually) accurately<br>
> > recognise modules, classes and functions from context, but we can't do<br>
> > the same for constants.<br>
> <br>
> <br>
> What are you basing that claim on? I can tell that math.pi, string.digits,<br>
> and timedelta.resolution are constants just fine.<br>
<br>
Sure, but only because you know the semantics that pi is a numeric <br>
constant, digits refers only to the Hindi-Arabic numerals 0...9, etc. I <br>
wouldn't have guessed that timedelta.resolution is a constant, because I <br>
don't know that module so well.<br>
<br>
But how about<br>
<br>
filename<br>
pattern<br>
location<br>
person<br>
sigma<br>
characters<br>
<br>
Which of those are constants?<br>
<br>
All of those are taken from real code I've written, except "characters" <br>
which I just made up. All of them have been constants in some modules <br>
and variables in others, except for sigma, but I'm not telling you which <br>
it was. Since it is so easy for you to tell a constant from a variable, <br>
you ought to be able to tell which it was. Right?<br>
<br>
Remember, the person reading your code is not necessarily an expert in <br>
the domain of your code. It might be trivial for you to say that <br>
spam.aardvark cannot possibly be anything but a constant, but to those <br>
who aren't experts in the domain, they might as well be metasyntactic <br>
variables.<br>
<br>
<br>
-- <br>
Steve<br>
_______________________________________________<br>
Python-ideas mailing list<br>
<a href="mailto:Python-ideas@python.org" target="_blank">Python-ideas@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/python-ideas" rel="noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/python-ideas</a><br>
Code of Conduct: <a href="http://python.org/psf/codeofconduct/" rel="noreferrer" target="_blank">http://python.org/psf/codeofconduct/</a><br>
</blockquote></div>