On Sat, Jan 5, 2019 at 9:59 AM Abe Dillon wrote:

Do you not have/use syntax highlighting? If not, why not? There's a right and wrong tool for everything. In the case of visually differentiating various kinds of code entities, the IDE is the right tool, all caps is not.

All-caps is a signal to the human or the IDE that this is never going to be mutated or rebound. How else do you convey that information? How does the IDE know this doesn't ever get changed? ChrisA

So you're saying we should prefer a future where it's an inconsistent mess? No. And please don't straw man. It's a very annoying argumentative tactic. I prefer a future where all caps aren't used. I understand that the change I propose won't magically transport us there, but I don't think it justifies encouraging all caps. As it is, the mix of all caps, camel-case, and snake-case IS and inconsistent and visual mess. Discouraging all caps will only result in a diminishing occurrence of all caps.

You mean it’s already an inconsistent mess? Hmm, maybe. I’d like to see some stats or something. You might be right!

it's.more important to have a standard than what that standard is. And we do have a strong standard today. I understand that there's a barrier to change, but there's also a circular logic to resisting change because adhering to a standard is good.

Agreed. It’s a tradeoff with the amount of time we spend in the ugly place between standards. Maybe it’s not so much time, or maybe it’s a minor annoyance and so it doesn’t matter how long we are in it. / Anders

How do you propose, instead, for the constantness of something to be indicated?

That's a good question. I honestly don't use constants all that much, I like to move such things out to config files. For a constant like math.pi, it's never been caps, yet people know it's not a great idea to change it. There are a lot of tools to indicate constantness: 1) provide a property to access an otherwise _plz_dont_touch_variable 2) Use an Enum 3) Use documentation to say: treat this as constant 4) Rely upon consenting adults to not change variables outside of scope. It's weird to manipulate math.pi because it's in a separate module. I stopped using all caps a long time ago and it just hasn't created a problem because manipulating global variables without knowing what they are is such a bad idea to begin with. On Fri, Jan 4, 2019 at 5:16 PM Chris Angelico wrote:

On Sat, Jan 5, 2019 at 10:10 AM Abe Dillon wrote:

...

...

So you're saying we should prefer a future where it's an inconsistent

mess?

No. And please don't straw man. It's a very annoying argumentative tactic. I prefer a future where all caps aren't used. I understand that the change I propose won't magically transport us there, but I don't think it justifies encouraging all caps. As it is, the mix of all caps, camel-case, and snake-case IS and inconsistent and visual mess. Discouraging all caps will only result in a diminishing occurrence of all caps.

...

it's.more important to have a standard than what that standard is. And we do have a strong standard today.

I understand that there's a barrier to change, but there's also a circular logic to resisting change because adhering to a standard is good.

How bad would it really be to remove the line about constants being all caps from PEP-8?

How do you propose, instead, for the constantness of something to be indicated?

ChrisA _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

Just to be clear here: you're trying to say that the ALL_CAPS_NAME convention is unnecessary, but you don't use constants. That kinda weakens your argument a bit :)

Just to be clear, I'm currently working in a Java shop where the code-styles are to use all caps for constants, enums, and class-level variables. Most classes in our code base declare a class-level "LOG" or "LOGGER" object. I've found that completely unnecessary. A simple "log" works just fine. I've never been tempted to write over it. It would be impossible in Java anyway since the guidelines are to declare everything "final" (yes... shoot me) anyway. I helped one of the higher-ups in the company write a Python script and he found the lack of straight-jacket harnesses extremely distressing. How could you write code without "final"? or "private"? or type checking?! You have to use consistent white space?!?! It's all Stockholm syndrome. The whole point of the all-caps globals is to tell you a lot about what

they are.

A lot? The only thing it canonically tells you is to not modify it which is my default assumption with any variable I didn't declare myself and also impossible to do in the case of enums. I will often use a module-level constant

for a file or path name; within the module, it is deliberately treated as a constant, but if you import the module somewhere else, you could reassign it before calling any functions in the module, and they'll all use the changed path.

Do you communicate that API through the variable name alone? How so? I would assume any module-level variables are not to be modified unless there was documentation stating otherwise. You really don't need a obnoxious shouty convention to tell people not to change things. It's up to you whether you actually use the all-caps convention in

your own code or not, but IMO it is an extremely useful convention to have in the toolbox, and should be kept.

My boss would say:

It's up to you whether you actually use final in your own code or not, but IMO it is an extremely useful tool to have in the toolbox, and should be kept. (and also you have to use it because it's in the style guide)

On Fri, Jan 4, 2019 at 5:41 PM Chris Angelico wrote:

On Sat, Jan 5, 2019 at 10:29 AM Abe Dillon wrote:

...

...

How do you propose, instead, for the constantness of something to be

indicated?

That's a good question. I honestly don't use constants all that much...

Just to be clear here: you're trying to say that the ALL_CAPS_NAME convention is unnecessary, but you don't use constants. That kinda weakens your argument a bit :)

...

1) provide a property to access an otherwise _plz_dont_touch_variable 2) Use an Enum 3) Use documentation to say: treat this as constant 4) Rely upon consenting adults to not change variables outside of scope. It's weird to manipulate math.pi because it's in a separate module.

I stopped using all caps a long time ago and it just hasn't created a problem because manipulating global variables without knowing what they are is such a bad idea to begin with.

The whole point of the all-caps globals is to tell you a lot about what they are. For instance, I will often use a module-level constant for a file or path name; within the module, it is deliberately treated as a constant, but if you import the module somewhere else, you could reassign it before calling any functions in the module, and they'll all use the changed path.

We use well-chosen variable names to avoid needing special properties or documentation to explain how something is to be used. It's far better to distinguish between "thing" and "things" than to have to say "thing" and "array_of_thing". The whole "consenting adults" policy has to be built on clear indications, and the name of something is a vital part of that.

It's up to you whether you actually use the all-caps convention in your own code or not, but IMO it is an extremely useful convention to have in the toolbox, and should be kept.

ChrisA _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

...

...

I will often use a module-level constant for a file or path name; within the module, it is deliberately treated as a constant, but if you import the module somewhere else, you could reassign it before calling any functions in the module, and they'll all use the changed path.

Do you communicate that API through the variable name alone? How so? I would assume any module-level variables are not to be modified unless there was documentation stating otherwise. You really don't need a obnoxious shouty convention to tell people not to change things.

Yeah. By naming it in all caps. That's exactly how that's communicated. Example: https://github.com/Rosuav/shed/blob/master/emotify.py#L6 By default, it's calculated from __file__, but if an external caller wants to change this, it's most welcome to. Since it's in all-caps, you don't have to worry about it being changed or mutated during the normal course of operation.

You made EMOTE_PATH all caps signifying it's a constant, then added a comment saying that it "Can be overwritten prior to calling get_emote_list". So not only was your naming convention, on its own, insufficient to explain the API of your code, but you're completely violating PEP-8 because your using the constancy convention on something that's *not* constant. That's 100% counterintuitive. You subvert the *one thing* that all-caps is supposed to communicate. My whole point is that the thing that all-caps communicates: "you shouldn't change this", is the default assumption for pretty-much every variable you encounter, so it's really not that helpful. If you snooped around and found that the pandas module had a variable called "cucumber" that doesn't appear in the docs at all, would you assume that it's kosher to assign a value to pandas.cucumber? Well, then, no, that's not "it's up to you". Something mandated by a

style guide is not a tool in your toolbox

Yes, and PEP-8 being the de-facto style guide for Python is the starting place for many mandatory Python style guides, which is why I'm arguing to remove the all caps BS from it. But if you leave that part out, then yes, 'final' becomes a

tool that you may use if you wish, or ignore if you wish.

Do you think we should add "final", "private", etc. to Python? The point was that such things are clearly not necessary, yet if you suggest removing them, you'll get the exact same "might as well keep it in the toolbox" reaction or worse. The code style guides at my work aren't unique, they've been recycled for decades. It's like day-light savings time. People have some vague notion that it might have been a good idea in the past and now we just keep going through the motions even though it makes no sense. You just can't shake the notion that somehow, typing in all caps is a great way to convey information in code, when it's an extremely obnoxious means of conveying information in any other written form. On Fri, Jan 4, 2019 at 6:23 PM Chris Angelico wrote:

On Sat, Jan 5, 2019 at 11:09 AM Abe Dillon wrote:

...

...

Just to be clear here: you're trying to say that the ALL_CAPS_NAME convention is unnecessary, but you don't use constants. That kinda weakens your argument a bit :)

Just to be clear, I'm currently working in a Java shop where the code-styles are to use all caps for constants, enums, and class-level variables. Most classes in our code base declare a class-level "LOG" or "LOGGER" object. I've found that completely unnecessary. A simple "log" works just fine. I've never been tempted to write over it. It would be impossible in Java anyway since the guidelines are to declare everything "final" (yes... shoot me) anyway. I helped one of the higher-ups in the company write a Python script and he found the lack of straight-jacket harnesses extremely distressing. How could you write code without "final"? or "private"? or type checking?! You have to use consistent white space?!?!

It's all Stockholm syndrome.

The fact that the all-caps convention is used differently (even wrongly) in your current Java employment doesn't really impact this.

...

...

The whole point of the all-caps globals is to tell you a lot about what they are.

A lot? The only thing it canonically tells you is to not modify it which is my default assumption with any variable I didn't declare myself and also impossible to do in the case of enums.

...

I will often use a module-level constant for a file or path name; within the module, it is deliberately treated as a constant, but if you import the module somewhere else, you could reassign it before calling any functions in the module, and they'll all use the changed path.

Do you communicate that API through the variable name alone? How so? I would assume any module-level variables are not to be modified unless there was documentation stating otherwise. You really don't need a obnoxious shouty convention to tell people not to change things.

Yeah. By naming it in all caps. That's exactly how that's communicated. Example:

https://github.com/Rosuav/shed/blob/master/emotify.py#L6

By default, it's calculated from __file__, but if an external caller wants to change this, it's most welcome to. Since it's in all-caps, you don't have to worry about it being changed or mutated during the normal course of operation.

...

...

It's up to you whether you actually use the all-caps convention in your own code or not, but IMO it is an extremely useful convention to have in the toolbox, and should be kept.

My boss would say:

...

It's up to you whether you actually use final in your own code or not, but IMO it is an extremely useful tool to have in the toolbox, and should be kept. (and also you have to use it

because it's in the style guide)

Well, then, no, that's not "it's up to you". Something mandated by a style guide is not a tool in your toolbox, it's a requirement of the project. But if you leave that part out, then yes, 'final' becomes a tool that you may use if you wish, or ignore if you wish. (Personally, I would ignore that one, with the exception of "public static final" as an incantation for "class-level constant".)

ChrisA _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

On Sat, Jan 5, 2019 at 11:58 AM Abe Dillon wrote:

You made EMOTE_PATH all caps signifying it's a constant, then added a comment saying that it "Can be overwritten prior to calling get_emote_list".

So not only was your naming convention, on its own, insufficient to explain the API of your code, but you're completely violating PEP-8 because your using the constancy convention on something that's not constant. That's 100% counterintuitive. You subvert the one thing that all-caps is supposed to communicate.

If "don't change this externally" is the default, why would we have a naming convention meaning "don't change this externally"? I think you're misunderstanding the way that module constants are used in Python. They CAN be overridden. That is part of the point. All-caps does *not* signify "don't override this". ChrisA

On Sat, Jan 5, 2019 at 1:11 PM Abe Dillon wrote:

...

All-caps does *not* signify "don't override this".

PEP-8 specifically says to use all caps to signify constants. What exactly do you think the word "constant" means? I know very well Python doesn't support actual constants and that anything can be overridden.

At this point, we're way off python-ideas territory. Might be time to reopen the subject on python-list - what IS a constant, who's allowed to change them, etc, etc, etc. ChrisA

בתאריך שבת, 5 בינו׳ 2019, 2:10, מאת Abe Dillon ‏

The whole point of the all-caps globals is to tell you a lot about what

...

they are.

A lot? The only thing it canonically tells you is to not modify it

Wrong. It also tells it's unlikely to be modified by the code that does declare it, which can really help when reaaoning about the code, or debugging it, as it makes many potential sources of bugs less likely. Elazar

On Fri, Jan 4, 2019 at 10:07 PM Bernardo Sulzbach wrote:

I'd suggest violating PEP-8 instead of trying to change it.

TBH even my bash global environment variables tend to become more and more lowercase ...

Is it that really obnoxious? Does using upper case for constants measurably slows down coders? Can you cite the actual papers describing such experiments that lead to this conclusion ? Because, from my experience having a visual clue that a value is a constant or an enum is something pretty useful. Surely, I'd hate reading a newspaper article where the editor generously sprinkled upper case words everywhere, but analogies only go so far, reading code have some similarities with reading prose, but still is not the same activity. Best, Marcos Eliziario Em ter, 29 de jan de 2019 às 20:30, Cameron Simpson escreveu:

On 29Jan2019 15:44, Jamesie Pic wrote:

...

On Fri, Jan 4, 2019 at 10:07 PM Bernardo Sulzbach wrote:

...

I'd suggest violating PEP-8 instead of trying to change it.

TBH even my bash global environment variables tend to become more and more lowercase ...

If you mean _exported_ variables, then this is actually a really bad idea.

The shell (sh, bash, ksh etc) makes no enforcement about naming for exported vs unexported variables. And the exported namespace ($PATH etc) is totally open ended, because any programme might expect arbitrary optional exported names for easy tuning of defaults.

So, you think, since I only use variables I intend and only export variables I plan to, I can do what I like. Example script:

a=1 b=2 export b

So $b is now exported to subcommands, but not $a.

However: the "exported set" is initially the environment you inherit. Which means:

Any variable that _arrives_ in the environment is _already_ in the exported set. So, another script:

a=1 b=2 # not exporting either

If that gets called from the environment where you'd exported $b (eg from the first script, which could easily be your ~/.profile or ~/.bashrc), then $b gets _modified_ and _exported_ to subcommands, even though you hadn't asked. Because it came in initially from the environment.

This means that you don't directly control what is local to the script and what is exported (and thus can affect other scripts).

The _only_ way to maintain sanity is the existing convention: local script variables use lowercase names and exported variables use UPPERCASE names. With that in hand, and cooperation from everyone else, you have predictable and reliable behaviour. And you have a nice visual distinction in your code because you know immediately (by convention) whether a variable is exported or not.

By exporting lowercase variables you violate this convention, and make your script environment unsafe for others to use.

Do many many example scripts on the web do the reverse: using UPPERCASE names for local script variables? Yes they do, and they do a disservice to everyone.

Cheers, Cameron Simpson _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

-- Marcos Eliziário Santos mobile/whatsapp/telegram: +55(21) 9-8027-0156 skype: marcos.eliziario@gmail.com linked-in : https://www.linkedin.com/in/eliziario/

Text in color or against black backgrounds is harder to read than black on white. See for example: https://trevellyan.biz/graphic-design-discussion-how-color-and-contrast-affe... Text where different words in the same sentence are in different colors is even harder to read. And I think we should totally ban anyone on the web from putting light gray text on a lighter gray background (see https://www.wired.com/2016/10/how-the-web-became-unreadable/ for a good discussion). Or to say that another way: I think we should totally ban anyone on the web from putting light gray text on a lighter gray background!! But many of us use editors that use color for syntax highlighting and we do that because projecting semantics onto the color axis works for us. So we don't ban colorizing text and we shouldn't. Capitalizing constants may be slightly harder to read but constants in code are the minority and emphasizing them is precisely the point. I'm MINUS_ONE on changing PEP 8. Make your own styleguide if you don't want to follow PEP 8 in your code. --- Bruce On Wed, Jan 30, 2019 at 11:48 AM Abe Dillon wrote:

...

Is it that really obnoxious?

EXTREMELY!

...

Does using upper case for constants measurably slows down coders? Can you cite the actual papers describing such experiments that lead to this conclusion ?

https://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so... https://en.wikipedia.org/wiki/All_caps#Readability https://uxmovement.com/content/all-caps-hard-for-users-to-read/ https://practicaltypography.com/all-caps.html

...

from my experience having a visual clue that a value is a constant or an enum is something pretty useful.

Do you have any proof that it's useful? Have you ever been tempted to modify math.pi or math.e simply because they're lower case? Have you ever stopped to wonder if those values change?

If the socket library used packet_host, packet_broadcast, etc. instead of PACKET_HOST, PACKET_BROADCAST, ETC. would you be confused about whether it's a good idea to rebind those variables? Would you be tempted to write the line of code: socket.packet_host = x?

It seems to me that nobody is actually considering what I'm actually talking about very carefully. They just assume that because all caps is used to convey information that information is actually important. Not just important, but important enough that it should be in PEP-8. They say I should just violate PEP-8 because it's not strictly enforced. It is strictly enforced in workplaces. I don't see why it can't be the other way around: PEP-8 doesn't say to use all caps, but if you want to it's OK.

...

Surely, I'd hate reading a newspaper article where the editor generously sprinkled upper case words everywhere

Exactly. If it's an eye-sore in every other medium, then it seems likely to me, the only reason programmers don't consider it an eye-sore is they've become inured to it.

...

but analogies only go so far, reading code have some similarities with reading prose, but still is not the same activity.

CAN you articulate what is DIFFERENT about READING code that makes the ALL CAPS STYLE less offensive?

On Tue, Jan 29, 2019 at 6:09 PM Marcos Eliziario < marcos.eliziario@gmail.com> wrote:

...

Is it that really obnoxious? Does using upper case for constants measurably slows down coders? Can you cite the actual papers describing such experiments that lead to this conclusion ? Because, from my experience having a visual clue that a value is a constant or an enum is something pretty useful. Surely, I'd hate reading a newspaper article where the editor generously sprinkled upper case words everywhere, but analogies only go so far, reading code have some similarities with reading prose, but still is not the same activity.

Best, Marcos Eliziario

Em ter, 29 de jan de 2019 às 20:30, Cameron Simpson escreveu:

...

On 29Jan2019 15:44, Jamesie Pic wrote:

...

On Fri, Jan 4, 2019 at 10:07 PM Bernardo Sulzbach wrote:

...

I'd suggest violating PEP-8 instead of trying to change it.

TBH even my bash global environment variables tend to become more and more lowercase ...

If you mean _exported_ variables, then this is actually a really bad idea.

The shell (sh, bash, ksh etc) makes no enforcement about naming for exported vs unexported variables. And the exported namespace ($PATH etc) is totally open ended, because any programme might expect arbitrary optional exported names for easy tuning of defaults.

So, you think, since I only use variables I intend and only export variables I plan to, I can do what I like. Example script:

a=1 b=2 export b

So $b is now exported to subcommands, but not $a.

However: the "exported set" is initially the environment you inherit. Which means:

Any variable that _arrives_ in the environment is _already_ in the exported set. So, another script:

a=1 b=2 # not exporting either

If that gets called from the environment where you'd exported $b (eg from the first script, which could easily be your ~/.profile or ~/.bashrc), then $b gets _modified_ and _exported_ to subcommands, even though you hadn't asked. Because it came in initially from the environment.

This means that you don't directly control what is local to the script and what is exported (and thus can affect other scripts).

The _only_ way to maintain sanity is the existing convention: local script variables use lowercase names and exported variables use UPPERCASE names. With that in hand, and cooperation from everyone else, you have predictable and reliable behaviour. And you have a nice visual distinction in your code because you know immediately (by convention) whether a variable is exported or not.

By exporting lowercase variables you violate this convention, and make your script environment unsafe for others to use.

Do many many example scripts on the web do the reverse: using UPPERCASE names for local script variables? Yes they do, and they do a disservice to everyone.

Cheers, Cameron Simpson _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

-- Marcos Eliziário Santos mobile/whatsapp/telegram: +55(21) 9-8027-0156 skype: marcos.eliziario@gmail.com linked-in : https://www.linkedin.com/in/eliziario/

_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

On Thu, Jan 31, 2019 at 8:23 AM Abe Dillon 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?

ttps://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so-hard-to-read https://en.wikipedia.org/wiki/All_caps#Readability https://uxmovement.com/content/all-caps-hard-for-users-to-read/ https://practicaltypography.com/all-caps.html

Nobody is saying that the *entire document* should be in all caps. This is a specific token, a specific identifier. Are English paragraphs hard to read because tokens like "HTML" and "IBM" are in all-caps?

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?

With constants that are taken directly from C, consistency is extremely helpful. Why is it called AF_INET6? Because it has exactly the same as AF_INET6 in C, or any other language that also has derived its socket handling from BSD sockets. (Which, for reference, is basically every language that has any sort of socket support.)

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.

That is not PEP 8's problem. The document stipulates that it is the standard for the Python standard library, nothing else. Are you going to appeal to Google to have *their* style guide changed too? A lot of people have adopted Google's style guide, and it explicitly says that module level constants *must* be in all caps.

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.

I don't think PEP 8 actually mandates that *all* constants be written in all caps. It says "usually". But you have many options here - ignore PEP 8, treat PEP 8 as a guideline, or just accept that ALL_CAPS_CONSTANTS actually do carry useful information in their names. ChrisA

On Thu, Jan 31, 2019 at 9:41 AM Abe Dillon wrote:

[ChrisA]

...

Nobody is saying that the *entire document* should be in all caps.

I've never claimed as much. Most of the reasons all caps harm readability hold true whether you're talking about a single word or entire document.

You have implied it by making the claim about single words, and then citing references that talk about entire documents.

[ChrisA]

...

Are English paragraphs hard to read because tokens like "HTML" and "IBM" are in all-caps?

Acronyms are a different use case for all caps. We can discuss the value proposition for those in another thread if you'd like. I will say that I read my share of research papers where acronyms tend to see heavy use and, yes; it can harm readability.

Initialisms (that aren't acronyms) carry information: you read them out letter by letter rather than as a word (ignoring phonograms etc). Constants carry information by being in all caps also.

[ChrisA]

...

Are you going to appeal to Google to have *their* style guide changed too?

That's comparing apples and oranges. Python is an open language with an ideas forum about how to improve things. Google generally isn't open to my suggestions. Any given company I work with is much more likely to enforce PEP-8 than Google's style guides. As far as I know, getting Google to adopt a given idea isn't a precondition for the Python community accepting said idea.

Both documents are specific to an original context, but have been adopted elsewhere. If your company has adopted PEP 8, that's your company's decision. It would equally be your company's decision to use the Google style guide, or a modified version of either, or a hybrid of both. If PEP 8 changes, will your company instantly change its policy to be "use this new version"? They don't have to.

[ChrisA]

...

treat PEP 8 as a guideline

Again, that's not always an option.

Again, that's not PEP 8's problem. ChrisA

On Wed, Jan 30, 2019 at 05:41:56PM -0600, Abe Dillon wrote:

I don't know how to make myself more clear. I haven't been talking about entire documents. Some of the links I provided discuss tests conducted on entire documents. That is not relevant to this discussion.

Then why on earth are you providing those links as support for your assertion that the use of a few all-caps identifiers anywhere on the page "destroys the visual flow of code" (your words) and reduces readability? Don't blame us for the fact that the links you provided don't actually support your assertions. You chose them, you posted them at least three times, if they don't support your position it is cheeky of you to tell us now that they are irrelevant. The links you have provided definitively support the idea that large paragraphs of all-caps text hurt readability, reducing reading speed by about 10%. But they say nothing about the cost of using the odd all-caps word here or there. Ten percent decrease in reading speed is nothing to sneer at, but it is a relatively minor cost. In any case, those readability tests were performed on ordinary non-programmers, reading prose text. For programmers reading code, I would expect that the physical cost of reading words is likely to be only a very small proportion of the total cost of comprehending the code. I've spent *hours* trying to understand the semantics of code that took seconds to read. Compared to that, what's plus or minus ten percent? But never mind, let's go with the 10% figure. That applies to an entire paragraph of all-caps, versus mixed case. It says nothing about the cost of using one or two, or even ten or twelve, all-caps identifiers in pages of code which is otherwise 95% or more mixed case. If 100% all-caps is 10% more costly to read, then 5% all-caps is probably no more than 0.5% more costly to read. Which puts it firmly in "margin of error" territory. -- Steven

On 30Jan2019 15:22, Abe Dillon 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...

"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

On 1/30/19 6:07 PM, David Mertz wrote:

On Wed, Jan 30, 2019, 4:23 PM Abe Dillon mailto:abedillon@gmail.com wrote:

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

I generally use 'from math import pi as PI' because the lower case is confusing and misnamed.

Another message here reminded me that the datetime classes are not named DateTime like they should be. Why not rename them, PI and E too, with suitable long-term deprecation period? (As it looks like ALL_CAPS is here to stay.) -Mike

On Fri, Feb 1, 2019 at 11:24 AM Abe Dillon wrote:

"why not make everything default to 'final' and put 'var' or something in-front of the few outliers?".

If it happens, it'll be another example of mainstream languages adopting ideas from functional programming. I love it when that happens, I just wish it didn't take decades.

On Fri, Feb 01, 2019 at 02:43:49PM -0500, Eric V. Smith wrote:

On 2/1/2019 1:59 PM, Mike Miller wrote:

...

Another message here reminded me that the datetime classes are not named DateTime like they should be.  Why not rename them, PI and E too, with suitable long-term deprecation period?

Because the hassle involved in making the change, supporting both for a long time, invalidating tons of working code, invalidating tutorials, migrating existing pickle files, etc. isn't worth any slight gain in consistency.

Indeed. If the change was going to be done, it should have been done in Python 3.0. Since we missed the opportunity, the benefit is too small to bother until the next(!) round of breaking changes in Python 5000 (if there ever is such a major backwards-incompatible version, which there probably won't be). Consistency is a Nice To Have, not a Must Have. The only exception to that is that I wish that ``object`` would be renamed to Object. That would distinguish between Object, the base class of all types, and object, an instance of some class. In my personal opinion, being more clear about that distinction would be worth the pain in ways that (say) renaming datetime to DateTime would not be. -- Steve

On Fri, Feb 01, 2019 at 11:07:04PM +0100, Anders Hovmöller wrote:

...

The only exception to that is that I wish that ``object`` would be renamed to Object. That would distinguish between Object, the base class of all types, and object, an instance of some class. In my personal opinion, being more clear about that distinction would be worth the pain in ways that (say) renaming datetime to DateTime would not be.

Could you detail what that pain would be?

That was described in the part of my email that you deleted. Quoting Eric: Because the hassle involved in making the change, supporting both for a long time, invalidating tons of working code, invalidating tutorials, migrating existing pickle files, etc. isn't worth any slight gain in consistency.

To me it seems like you'd have both names for a while with deprecation warnings. Doesn't sound too painful. Especially in the datetime case which is already quite painful.

What's painful about it? - the status quo means "no change", so there is no hassle there; - we don't have to support two names; - or manage depreciation warnings; - no working code is invalidated by "not changing" the class; - no tutorials or books are invalidated; - existing pickle files continue to work; - there are no questions on forums asking "what's the difference between datetime and DateTime, which should I use?" -- Steven

On Sat, Feb 02, 2019 at 12:06:47AM +0100, Anders Hovmöller wrote:

...

- the status quo means "no change", so there is no hassle there;

Not quite true. There is a constant hassle of "do I need to write datetime.datetime.now() or datetime.now()?"

My point was that there is no hassle from *making a change* if you don't actually make a change. (There may, or may not, be other, unrelated hassles.) Besides, I'm not seeing that this is any worse than any other import. Do I call spam.Eggs.make() or Eggs.make()? If you don't remember what you imported, the names don't make much difference. I accept that datetime.datetime reads a bit funny and is a bit annoying. If we had the keys to the time machine and could go back a decade to version 3.0, or even further back to 1.5 or whenever the datetime module was first created, it would be nice to change it so that the class was DateTime. But changing it *now* is not free, it has real, serious costs which are probably greater than the benefit gained.

I solved this at work by changing all imports to follow the "from datetime import datetime" pattern and hard banning the other statically in CI. But before that people suffered for years.

Oh how they must have suffered *wink* I'm surprised that you don't do this: from datetime import datetime as DateTime

I have a colleague who likes to point that the future is longer than the past. It's important to keep that perspective.

Actually, no, on average, the projected lifespan of technologies, companies and cultural memes is about the same as their current age. It might last less, or it might last more, but the statistical expectation is about the same as the current age. So on average, "the future" is about the same as "the past". Python has been around not quite 30 years now, so we can expect that it will probably last another 30 years. But chances are not good that it will be around in 300 years. -- Steve

Sent from my iPhone

On Feb 2, 2019, at 3:41 AM, Steven D'Aprano wrote:

...

On Sat, Feb 02, 2019 at 12:06:47AM +0100, Anders Hovmöller wrote:

...

- the status quo means "no change", so there is no hassle there;

Not quite true. There is a constant hassle of "do I need to write datetime.datetime.now() or datetime.now()?"

My point was that there is no hassle from *making a change* if you don't actually make a change. (There may, or may not, be other, unrelated hassles.)

Besides, I'm not seeing that this is any worse than any other import. Do I call spam.Eggs.make() or Eggs.make()? If you don't remember what you imported, the names don't make much difference.

I accept that datetime.datetime reads a bit funny and is a bit annoying. If we had the keys to the time machine and could go back a decade to version 3.0, or even further back to 1.5 or whenever the datetime module was first created, it would be nice to change it so that the class was DateTime. But changing it *now* is not free, it has real, serious costs which are probably greater than the benefit gained. Why can’t we put “now” as a property of the module itself, reccomend that, and formally deprecate but never actually remove datetime.datetime.now?

...

I solved this at work by changing all imports to follow the "from datetime import datetime" pattern and hard banning the other statically in CI. But before that people suffered for years.

Oh how they must have suffered *wink*

I'm surprised that you don't do this:

from datetime import datetime as DateTime

...

I have a colleague who likes to point that the future is longer than the past. It's important to keep that perspective.

Actually, no, on average, the projected lifespan of technologies, companies and cultural memes is about the same as their current age. It might last less, or it might last more, but the statistical expectation is about the same as the current age. So on average, "the future" is about the same as "the past".

Python has been around not quite 30 years now, so we can expect that it will probably last another 30 years. But chances are not good that it will be around in 300 years.

A big reason why projects last as long as you say they last is that the maintainers get un-ambitious, they get used to relaxing in the language they know so well, they are no longer keen on change. This kind of readability issue, datetime.now, is an example of what’s contributing to Python’s decline. Bottom line: if someone submits a PR for this, will anyone merge it?

-- Steve _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

On Sun, Feb 03, 2019 at 04:07:22PM +0000, Steve Barnes wrote:

Better yet why not also rename datetime.datetime to datetime.DateTime and include the line: datetime = DateTime.

That was already discussed in this thread. -- Steven

On 2/2/2019 11:56 PM, James Lu wrote:

Sent from my iPhone

...

On Feb 2, 2019, at 3:41 AM, Steven D'Aprano wrote:

...

Python has been around not quite 30 years now, so we can expect that it will probably last another 30 years. But chances are not good that it will be around in 300 years.

A big reason why projects last as long as you say they last is that the maintainers get un-ambitious, they get used to relaxing in the language they know so well, they are no longer keen on change.

This kind of readability issue, datetime.now, is an example of what’s contributing to Python’s decline.

Bottom line: if someone submits a PR for this, will anyone merge it?

I would not, and I don't think any other core dev would. There should be one way to do things (insert quibbles about PEP 20 here). I think it's detrimental to the language to introduce a new way of doing exactly the same thing that has existed for ages (maybe decades). And it would not be possible to remove the existing datetime.datetime.now without breaking tons of code, books, tutorials, Stack Overflow answers, etc. I realize we disagree about this, and it frustrates you. But Python has a long history of not making gratuitous changes such as this. Maybe that's one reason it's so popular? Besides: datetime.datetime.now is a pattern we use: classmethods that act as an alternate class constructor. There are tons of examples of this in the stdlib: pathlib.Path.home, factions.Fraction.from_float, and many, many others. These belong in the class that they return, not as a helper in the module. There are plenty of things that annoy me about Python libraries. Some of them I even wrote. But we're not going to start changing things solely for style or consistency issues. Eric

On Sat, Feb 02, 2019 at 11:56:47PM -0500, James Lu wrote:

...

I accept that datetime.datetime reads a bit funny and is a bit annoying. If we had the keys to the time machine and could go back a decade to version 3.0, or even further back to 1.5 or whenever the datetime module was first created, it would be nice to change it so that the class was DateTime. But changing it *now* is not free, it has real, serious costs which are probably greater than the benefit gained.

Why can’t we put “now” as a property of the module itself, reccomend that, and formally deprecate but never actually remove datetime.datetime.now?

The first half of that suggestion has merit. I would definitely appreciate a pair of top-level helper functions that returned the current date and current datetime. They might even be as simple as this: # In the datetime module today = date.today now = datetime.now But there is no reason to deprecate the existing functionality. It isn't broken or harmful. There's no need to remove it. Being able to construct a new date or datetime object using a method of the class is a perfectly natural thing to do. And deprecating a feature that you have no intention of removing just adds noise to the language. [...]

...

Actually, no, on average, the projected lifespan of technologies, companies and cultural memes is about the same as their current age. It might last less, or it might last more, but the statistical expectation is about the same as the current age. So on average, "the future" is about the same as "the past".

Python has been around not quite 30 years now, so we can expect that it will probably last another 30 years. But chances are not good that it will be around in 300 years.

A big reason why projects last as long as you say they last is that the maintainers get un-ambitious, they get used to relaxing in the language they know so well, they are no longer keen on change.

Possibly the most widely-used language in the world, C, is also far more conservative and slow-changing than Python. (Python is about in the middle as far as speed of change.) We put out new features roughly every 18 months. C brings them out about once a decade. Whether we love or hate C, it is pretty clear that it is not going away any time soon. -- Steven

On Wed, Jan 30, 2019 at 01:47:56PM -0600, Abe Dillon wrote:

...

Is it that really obnoxious?

EXTREMELY!

I don't agree with you that the use of one or two words in a sentence for EMPHASIS is obnoxious, and I don't writing a one-word sentence is a good test of that. In any case, even if it is the case that all-caps has the downside that it draws the eye ("shouty") more than necessary, I believe that the benefits of the convention outweigh that cost.

...

Does using upper case for constants measurably slows down coders? Can you cite the actual papers describing such experiments that lead to this conclusion ?

https://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so... https://en.wikipedia.org/wiki/All_caps#Readability https://uxmovement.com/content/all-caps-hard-for-users-to-read/ https://practicaltypography.com/all-caps.html

None of those "cite the actual papers" as requested, and only the Wikipedia page cites secondary sources. But that's okay, since we don't dispute that wall-to-wall paragraphs of all-caps are hard to read, we only dispute that the judicious and occasional use of all-caps to communicate metadata about what would otherwise appear to be a variable hurts readability in any meaningful sense. It isn't very interesting to say that it takes the average programmer (let's say) 250ms to read this line: with open(filename, 'w') as f: versus (let's say) 280ms to read this one: with open(FILENAME, 'w') as f: I don't know if that is true or not, but even if it is, I'm not particularly interested in optimizing the time it takes to read individual words. When it comes to coding, the time used scanning over a line of text is typically insiginificant compared to the time needed to understand the semantics and context. It isn't that I particularly want to slow down reading of indivudual words, but I'm willing to lose (let's say) 10 to 20 milliseconds to read FILENAME versus filename, so that I don't have to spend (let's say) 30 to 120 seconds trying to determine whether or not the value of filename has been rebound somewhere I didn't expect and that's why my script is writing to the wrong file.

...

from my experience having a visual clue that a value is a constant or an enum is something pretty useful.

Do you have any proof that it's useful?

Not peer-reviewed, no, but from my own experience I know that generally speaking when I'm trying to understand the semantics of unfamiliar code (even if that is code I wrote myself!) if I see an ALLCAPS name, I generally know that on a first pass I can treat it as a given and ignore it without caring about its actual value. There are exceptions: for example, if there's a bug in my regex, then I do have to care about the value of PATTERN. If I'm writing to the wrong file, then I do have to care about the name of FILENAME. But even then, I can guess that the value is only set in one place. If there's a bug in my regex PATTERN, I can fix it once at the top of the module, and not worry about other parts of the script or library re-binding the value.

Have you ever been tempted to modify math.pi or math.e simply because they're lower case? Have you ever stopped to wonder if those values change?

This is a bit of a red herring (but only a bit) because the major value for signalling constantness is not so much as a warning to the *writer* not to change them, but to the *reader* that in well-written code, they haven't been changed. Obviously you can't have the second without the first, but since code is read more than it is written, the second occurs much more often. When it comes to math.pi and math.e, why would you want to change them? What is your use-case for changing them? I actually do have one. Many years ago, I wondered whether changing math.pi would change how math.sin, cos and tan work. So I tried this: py> import math py> math.cos(2*math.pi) # Period of cosine is 2π. 1.0 py> math.pi = 3 # Change the universe! π is now three exactly. py> math.cos(2*math.pi) # Should still be 1, right? 0.960170286650366 I learned that the trig functions don't work that way. Ever since then, I've never had any reason to want to change the value of math.pi. What would be the point?

If the socket library used packet_host, packet_broadcast, etc. instead of PACKET_HOST, PACKET_BROADCAST, ETC. would you be confused about whether it's a good idea to rebind those variables?

If they are variables, then by definition they must vary. If they vary, there must be reasons to rebind them. Since these are not flagged as "private" with a leading underscore, presumably they are part of the public API, so I would expect that, yes, rebinding those variables was a good idea. Since I'm not a domain expert when it comes to sockets, I would probably spend many minutes, maybe hours, trying to work out what part of the socket API requires me to set these global variables, and why. But in reality, since they are clearly flagged as constants, I can assume that they are intended as read-only constants, not global variables. I don't need to be a domain expert on sockets to know that rebinding PACKET_HOST is a bad idea, I just need to know that it isn't supported by the socket module. (The danger in asking rhetorical questions is that sometimes the answer isn't the one you expected.)

It seems to me that nobody is actually considering what I'm actually talking about very carefully. They just assume that because all caps is used to convey information that information is actually important.

Or maybe some of us have thought carefully about what you have said, and concluded that you are making an unjustified micro-optimization for reading time as measured by eye-tracking time over individual words, at the cost of total editing and debugging time.

Not just important, but important enough that it should be in PEP-8. They say I should just violate PEP-8 because it's not strictly enforced. It is strictly enforced in workplaces.

Clearly it isn't "strictly enforced". Because the single most important rule of PEP 8 is the one mentioned right at the start about knowing when to break all the other rules. If your workplace forbids any exceptions to the other PEP 8 rules, then they are violating the most important PEP 8 rule of all.

...

Surely, I'd hate reading a newspaper article where the editor generously sprinkled upper case words everywhere

Exactly. If it's an eye-sore in every other medium, then it seems likely to me, the only reason programmers don't consider it an eye-sore is they've become inured to it.

It isn't an eyesore in every other context. You are making a logical error in assuming that since wall-to-wall all-caps significantly hurt readability, so much individual all-caps words. This is simply not correct. Drinking six litres of water in a single sitting will likely kill an adult; therefore (according to your reasoning) we shouldn't drink even a single sip of water. https://www.medicaldaily.com/taste-death-ld50-3-popular-drinks-can-kill-you-... Even if eye-tracking experiments show that it takes a fraction of a second longer to read that one word, that doesn't correspond to "hurting readability" in any meaningful sense. Optimizing for eye-tracking time for its own sake is not a useful thing for programmers to worry about.

...

but analogies only go so far, reading code have some similarities with reading prose, but still is not the same activity.

CAN you articulate what is DIFFERENT about READING code that makes the ALL CAPS STYLE less offensive?

You are misusing the word "offensive" there. Please don't use it to mean "hard to read" or "annoying". Again, to answer your rhetorical question in a way you probably hoped it wouldn't be answered: because we don't write wall-to-wall all-caps code (at least not in Python). We're not likely to have six all-caps names in a single expression; we're probably not likely to have six all-caps names in an entire function. Consequently the cost of reading the all-caps word is tiny, and the benefit is greater. Just as it is for using all-caps for initialisms and acronyms like AFL, USA, FAQs, LD50, LED, PRC, PC, etc. Or for the occasional use for emphasis. Etc. -- Steve

On Wed, Jan 30, 2019 at 5:54 PM Jamesie Pic wrote:

What do you think about the cost of typing caps ? Surely, shift aggravates repeated strain injury.

We spend more time reading code than typing it— even more so with code completion. It’s a style *guide* folks — let it go! - CHB

-- ∞ _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

-- Christopher Barker, PhD Python Language Consulting - Teaching - Scientific Software Development - Desktop GUI and Web Development - wxPython, numpy, scipy, Cython

On Thu, Jan 31, 2019 at 1:05 PM Abe Dillon wrote:

[Christopher Barker]

...

It’s a style *guide* folks — let it go!

While I don't harbor any delusions that this is going anywhere (given the feedback so far), that's a double edged sword. It's also an extremely benign request, why fight so hard?

I think you should be able to tell from the backlash that this is NOT a benign request. You're asking for the standard library's style guide to be changed, purely for the convenience of some company that is pigheadedly refusing to read the first few paragraphs of a document that it is blindly adopting. Time to take this to python-list? ChrisA

Sure everyone knows what it means, but it's meaning is essentially useless because the default assumption when you encounter a variable you don't know, is that you shouldn't overwrite it. If you found a module-level variable in Pandas named cucumber, would you immediately assume you can write whatever value you want to pandas.cucumber because it isn't in all caps? On Fri, Jan 4, 2019 at 6:04 PM Michael Foord wrote:

On Fri, 4 Jan 2019 at 19:02, Abe Dillon wrote:

...

I keep coming back to this great video https://vimeo.com/74316116 about coding style, and one point in particular rings true to me: ALL_CAPS_IS_OBNOXIOUS

I really like the convention. It's nice and clear and absolutely everyone knows what it means.

Michael

...

It destroys the visual flow of code and for what? To signify a global, constant, or Enum? Is that really so important? I don't think so. I think the all caps style has out-lived its usefulness and needs to go the way of the dodo.

The last time I saw all caps used appropriately was in a YouTube comment where some guy was ranting about the communist Jewish banker conspiracy to control the world. In that case, all caps clearly communicated to me that the person was a frothing lunatic (thought find the idea of communist bankers intriguing).

Currently PEP-8 prescribes all caps for constants https://www.python.org/dev/peps/pep-0008/#constants and uses the all cap variable "FILES" as an example in a different section. https://www.python.org/dev/peps/pep-0008/#when-to-use-trailing-commas It also appears to be the defacto-standard for enums (based on the documentation https://docs.python.org/3/library/enum.html#creating-an-enum)

I don't think it's necessary to make any breaking changes. Just pep-8 and (of less importance) spurious documentation examples. _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

--

http://www.michaelfoord.co.uk/

May you do good and not evil May you find forgiveness for yourself and forgive others May you share freely, never taking more than you give. -- the sqlite blessing http://www.sqlite.org/different.html

On Sat, 5 Jan 2019 at 00:05, Michael Foord wrote:

On Fri, 4 Jan 2019 at 19:02, Abe Dillon wrote:

...

I keep coming back to this great video about coding style, and one point in particular rings true to me: ALL_CAPS_IS_OBNOXIOUS

I really like the convention. It's nice and clear and absolutely everyone knows what it means.

So do I. And I just looked at the linked video, and notice that it's originally about Java. There's no obvious reason to me that Java conventions should transfer to Python. Java has "public static final" to declare actual constants (yay Java terseness! :-)) and has no global scope (so the all-caps is at class level, not global). -1 on this proposal. With all the "style checker" tools out there, even if it's only an optional suggestion, it'll end up getting mandated all over the place... Paul

On Sat, 5 Jan 2019 at 02:46, David Mertz wrote:

Like everyone other than Abe in this thread, I find judicious use of CONSTANTS to be highly readable and useful.

Yes, there is a little wiggle room about just how constant a constant has to be since Python doesn't have a straightforward way to create real constants. Very rarely I might change a value named in all caps. But the distinction between a value intended as fixed and one I merely probably won't change is worth marking typographically.... Especially since there's no actual Python semantics enforcing it.

There is. Mypy supports final names, final methods and whatnot https://mypy.readthedocs.io/en/latest/final_attrs.html Anyway I don't see a problem in using CAPS for constants, finally it is just a style guide, Python will work even with class sTYLISH_oNE: ... -- Ivan

On 1/5/19 12:21 PM, Mike Miller wrote:>

On 1/5/19 12:34 AM, Ivan Levkivskyi wrote:

...

There is. Mypy supports final names, final methods and whatnot https://mypy.readthedocs.io/en/latest/final_attrs.html

Believe this^^ is the best answer, unfortunately buried.

The type hinting is physically separate (often in a different module) than the usage. If I'm looking at some code that uses the constant, the type hint is somewhere else.

Use typing hints for constants and tools that support them, and all-caps is no longer needed.

Requiring a tool/IDE to highlight this attribute is a step backwards. Can your email client find the type hint when it's in some other python module? Will proponents of type hints to provide this information also type them into answers on Stack Overflow? Dan

[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: ttps://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so-hard-to-read https://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so... https://en.wikipedia.org/wiki/All_caps#Readability https://uxmovement.com/content/all-caps-hard-for-users-to-read/ https://practicaltypography.com/all-caps.html [Steven D'Aprano]

<< DUP2 DIV SWAP OVER * ROT SWAP - >> The flow is fine if you know how to read reverse Polish notation ("Yoda speak"). It flows from left to right, and top down, same as English. Only the word order is different. The flow would be precisely the same if it were written like this: << dup2 div swap over * rot swap - >>

It's not precisely the same to me. My eye is drawn heavily to "dup2" in the latter. In the former my eye isn't drawn strongly to anything in particular. It's slightly drawn to the asterisk. I suppose I should clarify that when I talk about "visual flow" I mean how my eye is drawn around the media. [Steven D'Aprano]

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. [Steven D'Aprano]

What naming convention would you suggest for distinguishing between constants and variables?

None. You don't need one. [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. On Fri, Jan 4, 2019 at 9:42 PM Steven D'Aprano wrote:

On Fri, Jan 04, 2019 at 01:01:51PM -0600, Abe Dillon wrote:

...

I keep coming back to this great video https://vimeo.com/74316116 about coding style, and one point in particular rings true to me: 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.

To me, long lines spoil the visual flow of code (especially if they are long enough that I have to scroll horizontally to see the end).

To me, sudden blocks of unexpected indentation spoil the visual flow of code. (Fortunately, this is rare in Python.)

I've looked over code in the standard library, my own code, and third-party libraries, and I don't see that the choice of name disrupts the flow of code, whether it is written in CamelCase of lowercase or ALLCAPS or even rAnSOmenOTecAse. (Although I admit that last one is quite hard to read...)

I have a bunch of code written in RPL for the HP-48GX calculator, and the convention there is that nearly everything is written in allcaps. Here's an equivalent function to Python's divmod():

<< DUP2 DIV SWAP OVER * ROT SWAP - >>

The flow is fine if you know how to read reverse Polish notation ("Yoda speak"). It flows from left to right, and top down, same as English. Only the word order is different. The flow would be precisely the same if it were written like this:

<< dup2 div swap over * rot swap - >>

Where RPL does suffer from the lack of visual flow is the lack of structure to the code. In Python terms, it would be as if we wrote:

def function(): if condition: for x in sequence: do_this() do_that() endfor else: do_something_else() endif

Ouch.

The bottom line is, I don't agree that the visual flow of code is negatively affected, or affected at all, by the shape of individual words in the code.

...

and for what? To signify a global, constant, or Enum? Is that really so important? I don't think so.

I think the convention is useful, of moderate importance, and I think Python code would be ever-so-slightly harder to understand without it.

I rarely, if ever, use allcaps for constants defined and used in a single function, but that's because my functions are typically short enough that you can fit the entire function on screen at once and tell that the name is defined once and never re-bound, hence a constant.

Where the naming convention really makes sense is for module-level constants, where the initial binding is typically separated from the eventual use by a lot of time and space, I think it is useful to have a simple naming convention to distinguish between variables and constants. When I see this in the middle of a function:

def foo(): ... process(spam, FILENAME, eggs, ...) ...

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. So yes, having a naming convention for constants is useful.

And FILENAME is much better than cfilename or kfilename or constant_filename_please_dont_rebind_ok_thx *wink*

What naming convention would you suggest for distinguishing between constants and variables?

I suppose one might argue that we don't need to care about the semantics of which names are variables and which are constants. In fairness, we cope quite well with modules, classes and functions being effectively constants and yet written in non-allcaps.

But on the other hand, we generally can recognise modules, classes and functions by name and usage. We rarely say "process(module)", but we might say "process(module.something)". Classes have their own naming convention. So the analogy between global constants which don't use the allcaps convention (namely modules, classes and functions) and global constants which do is fairly weak. We can (usually) accurately recognise modules, classes and functions from context, but we can't do the same for constants.

...

Currently PEP-8 prescribes all caps for constants https://www.python.org/dev/peps/pep-0008/#constants and uses the all cap variable "FILES" as an example in a different section. https://www.python.org/dev/peps/pep-0008/#when-to-use-trailing-commas It also appears to be the defacto-standard for enums (based on the documentation < https://docs.python.org/3/library/enum.html#creating-an-enum> )

That's because the typical use for enums is as constants. If I had a *variable* which merely held an enum, I wouldn't use allcaps:

# No! Don't do this! for MYENUM in list_of_enums: if condition(MYENUM): MYENUM = something_else() process(MYENUM)

-- Steve _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

[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 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

On Wed, Jan 30, 2019 at 03:51:22PM -0600, Abe Dillon wrote: 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...

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@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

[Steven D'Aprano]

I've just watched it, ... it is a great video.

I'm really glad you did. I don't think many have, which I can't really blame anyone for because it's rather long, but if all this thread accomplishes is a few more people seeing that video, it'll have been worth it. [Steven D'Aprano]

I don't agree with everything he says, but even where I disagree it is great food for thought.

Yes, I disagree about his anti-dependency-injection stance. [Steven D'Aprano]

IDEs rot the brain.

He advocates for the use of "extract method" only 12 minutes into the talk. This comes off as Socrates famous warning that written language would, "create forgetfulness in the learners’ souls, because they will not use their memories.” No, IDEs are tools. Tools are generally meant to solve problems. He laments that IDEs can encourage pointless boilerplate, but tools don't have to include "the ghost of Clippy". I know this is a jab at my suggestion that an IDE could help communicate what is global (which, yes; is not synonymous w/ constant, though it usually should be) via syntax highlighting. I wonder if you believe that syntax highlighting "rots the brain"? [Steven D'Aprano]

the speaker makes an excellent point that in Java, you don't need a naming convention for constants because the compiler will give an error if you try to write to a constant.

That's not the only argument he makes against all caps constants, though I agree that it's the strongest argument against all caps in Java. I largely agree with the rest of your post. I just don't think we need a naming convention for constants. On Fri, Jan 4, 2019 at 10:21 PM Steven D'Aprano wrote:

On Fri, Jan 04, 2019 at 01:01:51PM -0600, Abe Dillon wrote:

...

I keep coming back to this great video https://vimeo.com/74316116

I've just watched it, its a bit slow to start but I agree with Abe that it is a great video. (And not just because the speaker agrees with me about 80 columns :-)

I don't agree with everything he says, but even where I disagree it is great food for thought. I *strongly* suggest people watch the video, although you might find (as I did) that the main lessons of it are that many common Java idioms exist to work around poor language design, and that IDEs rot the brain.

*semi-wink*

Coming back to the ALLCAPS question, the speaker makes an excellent point that in Java, you don't need a naming convention for constants because the compiler will give an error if you try to write to a constant.

But we don't have that in Python. Even if you run a linter that will warn on rebinding of constants, you still need a way to tell the linter that it is a constant.

The speaker also points out that in programming, we only have a very few mechanisms for communicating the meaning of our code:

- names; - code structure; - spacing (indentation, grouping).

Code structure is set by the language and there's not much we can do about it (unless you're using a language like FORTH where you can create your own flow control structures). So in practice we only have naming and spacing.

That's an excellent point, but he has missed one more:

* naming conventions.

In Python, we use leading and trailing underscores to give strong hints about usage:

_spam # private implementation detail

__spam # same, but with name mangling

__spam__ # overload an operator or other special meaning

spam_ # avoid name clashes with builtins

We typically use CamelCase for classes, making it easy to distinguish classes from instances, modules and functions.

And we use ALLCAPS for constants. If that's not needed in Java (I have my doubts...) we should also remember the speaker's very good advice that just because something is needed (or not needed) in language X, doesn't mean that language Y should copy it.

-- Steve _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/