AMEND PEP-8 TO DISCOURAGE ALL CAPS
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 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.
IMO it's good to have some sort of visual differentiation between constants and normal values. A lot of camelCase-based style guides use a k prefix (e.g. kMyValue), but Python doesn't use it (other than PascalCase for classes). If there were to be an alternative to ALL_CAPS for constants, I guess maybe it'd also be PascalCase? That being said, Dart 2 has dropped ALL_CAPS constants from its style guide, and although everyone's survived just fine, I do somewhat miss being able to immediately be able to see where something is coming from solely from the case. Side note: it seems like ALL_CAPS kind of came from macros being using for constants in C and persisted. -- Ryan (ライアン) Yoko Shimomura, ryo (supercell/EGOIST), Hiroyuki Sawano >> everyone else https://refi64.com/ On Fri, Jan 4, 2019, 1:02 PM Abe Dillon <abedillon@gmail.com 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. On Fri, Jan 4, 2019 at 1:13 PM Ryan Gonzalez <rymg19@gmail.com> wrote:
On Sat, Jan 5, 2019 at 9:59 AM Abe Dillon <abedillon@gmail.com> 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
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.
This is an argument against: - the line length limit (because the IDE should just soft break lines in a super nice way) - explicit “self.” (swift does this with syntax highlighting for example) - CamelCase for classes/types (actually python does a bad job here anyway with int, str, datetime, etc) I’m not saying I disagree but we should be aware that this is the argument. (and as ChrisA rightly points out it’s not fully applicable to constants anyway) / Anders
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? On Fri, Jan 4, 2019 at 2:55 PM Anders Hovmöller <boxed@killingar.net> 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.
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 <rosuav@gmail.com> wrote:
On Sat, Jan 5, 2019 at 10:29 AM Abe Dillon <abedillon@gmail.com> 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 :)
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
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
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:
On Fri, Jan 4, 2019 at 5:41 PM Chris Angelico <rosuav@gmail.com> wrote:
On Sat, Jan 5, 2019 at 11:09 AM Abe Dillon <abedillon@gmail.com> wrote:
The fact that the all-caps convention is used differently (even wrongly) in your current Java employment doesn't really impact this.
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.
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
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 <rosuav@gmail.com> wrote:
Looking at the arguments regarding rendering existing code non-PEP-8-compliant, I think if we were to make this change it should be made in Python 4.0, or whatever the next backwards-incompatible version will be. However, personally I disagree with the fundamental assertion that ALL_CAPS is always ugly. In my humble opinion, when used sparingly (as it is according to PEP 8), they make for a good distinguisher from regular_variables or ClassNames. Since python doesn’t have a “const” or “final” keyword like many strongly typed languages, IDEs would otherwise have a hard time distinguishing between constants and variables. (Although it’s up for debate whether it’s important to developers if this disambiguation is present.) Sent from my iPhone On Jan 4, 2019, at 7:58 PM, Abe Dillon <abedillon@gmail.com> wrote:
On Sat, Jan 5, 2019 at 11:58 AM Abe Dillon <abedillon@gmail.com> 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
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. Your example goes against the convention of using all caps to signify constants and it's a bad design all around. You would be better off with: def get_emote_lits(root = os.path.normpath(__file__ + "/../emotes")): ... # congratulations, you've re-invented the default parameter in a more clunky way! I don't know many APIs built around having you fiddle with module-level variables, it seems like an anti-pattern to me.
If "don't change this externally" is the default, why would we have a naming convention meaning "don't change this externally"?
Modules and Classes and functions typically expose functionality while the purpose of most other objects is to encapsulate state, so it makes sense that attributes would be read/write by default, though some even disagree on that point. I'm not a hard-core functional programming fanatic, so I'm not about to argue that everything should be read-only by default. I also think you're playing dumb to avoid confronting my point: If you found that there was an undocumented module-level attribute in pandas, what would be your initial assumption? If it's not all caps, is it fair game to override it? Can you re-write your emote code so that it's clear that the emote-path variable is part of the API *without* any documentation? How much does all caps really communicate? On Fri, Jan 4, 2019 at 7:16 PM Chris Angelico <rosuav@gmail.com> wrote:
On Sat, Jan 5, 2019 at 1:11 PM Abe Dillon <abedillon@gmail.com> 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
Dnia January 5, 2019 12:09:44 AM UTC, Abe Dillon <abedillon@gmail.com> napisał(a):
It also tells anyone, who is browsing a code, which values come from a spec of some kind (e.g. network protocols, file formats etc.)
which is my default assumption with any variable I didn't declare myself
It has been quite some time since I have learnt to avoid arguments like "I can do it, can everynoe else", because they are false. I like ALL_CAPS and other typographic clues, because I do a lot of integration work and I don't use IDE to browse every file I need to read. -- Łukasz Stelmach z podróży
בתאריך שבת, 5 בינו׳ 2019, 2:10, מאת Abe Dillon <abedillon@gmail.com>
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
I disagree. Changing this in the PEP will make an absurd amount of code which is PEP-8 compliant no longer so. Also, the refactoring may not always be trivial as the lowercase names may already be in use. I'd suggest violating PEP-8 instead of trying to change it.
Changing this in the PEP will make an absurd amount of code which is PEP-8 compliant no longer so.
It depends on how we change it. There's plenty of room to compromise between explicitly mandating all caps and explicitly forbidding all caps. We could simply remove the section that says to use all caps for constants. We could replace that section with a statement that while it's discouraged, it doesn't violate pep8 when used for constants. We could change some of the documentation (especially around enums) to show non-all-caps style is acceptable. etc. On Fri, Jan 4, 2019 at 3:06 PM Bernardo Sulzbach < bernardo@bernardosulzbach.com> wrote:
On 29Jan2019 15:44, Jamesie Pic <jpic@yourlabs.org> wrote:
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 <cs@cskk.id.au>
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 <cs@cskk.id.au> escreveu:
-- 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/
Is it that really obnoxious?
EXTREMELY!
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:
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 <abedillon@gmail.com> wrote:
Capitalizing constants may be slightly harder to read but constants in code are the minority and emphasizing them is precisely the point.
The question I'm trying to get everyone to actually think about: Is the communication of constancy via ALL CAPS so important that it must be in PEP-8 despite the documented harm that all caps does to readability? 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 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. Consider that math.pi and math.e are constants that are not all caps, have you ever been tempted to re-bind those variables? 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. 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? 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. On Wed, Jan 30, 2019 at 2:01 PM Bruce Leban <bruce@leban.us> wrote:
On Thu, Jan 31, 2019 at 8:23 AM Abe Dillon <abedillon@gmail.com> wrote:
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
[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. [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. [ChrisA]
With constants that are taken directly from C, consistency is extremely helpful.
That's fair. I can live with it. The socket module was just an example. There are several examples of all caps that aren't inherited from other sources. If datetime.MINYEAR and datetime.MAXYEAR were datetime.minyear and datetime.maxyear what do you think the consequences would be? Do you really think it's less clear? Do you think timedelta.min, timedelta.max, and timedelta.resolution aren't clear enough? How about string.digits? Should those shout at you that they're constants? Why or why not? [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. [ChrisA]
treat PEP 8 as a guideline
Again, that's not always an option. On Wed, Jan 30, 2019 at 3:41 PM Chris Angelico <rosuav@gmail.com> wrote:
On Thu, Jan 31, 2019 at 9:41 AM Abe Dillon <abedillon@gmail.com> wrote:
You have implied it by making the claim about single words, and then citing references that talk about entire documents.
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.
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.
Again, that's not PEP 8's problem. ChrisA
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. Please cut out the pedantry. It's aggravating and doesn't contribute to the discussion. It comes of as you trying to score "points" in a discussion for being more "technically correct". Example B:
I'm not talking about acronyms OR initialisms **rolls eyes extremely hard**. If you want to discuss whether HttpClient or HTTPClient is more acceptable, go start another thread. I've already responded to this.
This conversation isn't going to go anywhere if you ignore half of what I write.
It's my problem. It's a problem I have to deal with. It's a problem that doesn't need to be a problem. It's a problem that can be solved by modifying PEP-8. I don't even know what you mean by something being "PEP 8's problem". If you can't contribute to the discussion in a meaningful way, then why even respond? On Wed, Jan 30, 2019 at 5:24 PM Chris Angelico <rosuav@gmail.com> wrote:
On Wed, Jan 30, 2019 at 05:41:56PM -0600, Abe Dillon wrote:
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 1/30/2019 6:41 PM, Abe Dillon wrote: <see title> I think continued discussion is pretty useless. 1. Most everything relevant has been said, likely more than once, and 2. The required core-developer support does not exist. PEP 8 was written by Guido with input from other core developers. As Chris said, it defines itself in the opening paragraphs as a "guideline" for the "code in the stdlib". It also disclaims a straightjacket approach. We seldom revise the PEP. Doing so would require initial support from a core developer who garnered more more support. I am not fond of caps either, but not displeased enough to promote the proposal. (What I would like is clarification (from Guido or co-authors) what a 'constant' means in the context.) Abe, if an employer imposes PEP 8 on employees, especially in an overly rigid manner that the PEP discourages, that is an issue between the employer and employees, It is not the problem of Guido and other core developers. -- Terry Jan Reedy
On 30Jan2019 15:22, Abe Dillon <abedillon@gmail.com> wrote:
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."
"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."
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.
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.
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.
Arguing that "nobody has to violate PEP-8" by the mechanism of just dropping recommendations from it isn't very sound, IMO. If your in house style eschews caps for constants, go right ahead. Nobody will stop you. PEP-8 is primarily for the stdlib, where like any shared body of code it is useful to have common style. Plenty of places use PEP-8 as a basis - it is reasonable, and it gets you a fairly complete style guide from day 1. By all means diverge from it on a reasoned basis in your own code or within your own organisation. I do in my personal code: primarily 2 space indentation instead of 4, and my docstring formatting differs as well. And correspondingly, feel free to document your reasons for diverging. They may be universally valid or domain specific; provide such context. But I suspect you'll not get much traction on changing PEP-8 itself in this aspect because the convention is widely liked. Finally, I've worked in ALL CAPS programming environments. BASIC and assembler were traditionally written in all caps. Also FORTRAN. Also Modula-3, at least for its keywords (IF, etc). On the whole I think the world is a better place for being mostly lower case. To such an extent that I wrote a preprocessor for all my Modula-3 to transcribe my personal lower case programmes to upper case for the compiler. But the flip side of being in a mostly lower case world is that having occasional upper case as a standout formatting for particular entities sudden has more value. And that value has been used for constants for a long time with, IMO, some benefit. Cheers, Cameron Simpson <cs@cskk.id.au>
On Wed, Jan 30, 2019, 4:23 PM Abe Dillon <abedillon@gmail.com wrote:
Consider that math.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.
On 1/30/19 6:07 PM, David Mertz 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? (As it looks like ALL_CAPS is here to stay.) -Mike
[Mike Miller]
Another message here reminded me that the datetime classes are not named DateTime like they should be.
There are a few strange conventions in programming that seem almost backwards. In prose, we capitalize proper nouns, but rarely class-type nouns. Bullwinkle is a moose, not bullwinkle is a Moose. It seems the built-ins like int, str, list, dict, etc. get it right, then it's reversed for everything else. [Mike Miller]
There's a Java programming guideline at my workplace that you're supposed to put "final" in-front of pretty much everything because it supposedly makes code easier to reason about. I've since found that the Java community largely supports this idea <http://www.javapractices.com/topic/TopicAction.do?Id=23> (not just my company), which raises the question, "why not make everything default to 'final' and put 'var' or something in-front of the few outliers?". My default assumption for any variable not in the immediate scope is that it's intended to be read-only unless the code I'm reading modifies it. Maybe module-level variables and class-level variables should be all caps if they're NOT constant because then I'd want them to yell at me that they're a potential hazard. Anyway, I thought others might find that to be mildly interesting food for thought. Sorry for bumping this thread again... On Fri, Feb 1, 2019 at 12:59 PM Mike Miller <python-ideas@mgmiller.net> wrote:
On Fri, Feb 1, 2019 at 11:24 AM Abe Dillon <abedillon@gmail.com> 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 2/1/2019 1:59 PM, Mike Miller wrote:
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.
(As it looks like ALL_CAPS is here to stay.)
Yes, I'd say so. Eric
On Fri, Feb 01, 2019 at 02:43:49PM -0500, Eric V. Smith wrote:
On 2/1/2019 1:59 PM, Mike Miller wrote:
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:
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.
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
- 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()?" 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. I have a colleague who likes to point that the future is longer than the past. It's important to keep that perspective. Also Python is still growing so there are more future users than current users. We should take this into account also. / Anders
On Sat, Feb 02, 2019 at 12:06:47AM +0100, Anders Hovmöller wrote:
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.
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
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?
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 Sun, Feb 3, 2019 at 7:57 AM James Lu <jamtlu@gmail.com> wrote:
This kind of readability issue, datetime.now, is an example of what’s contributing to Python’s decline.
Python's decline??? https://pypl.github.io/PYPL.html
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 <steve@pearwood.info> wrote:
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
I know I argued for changing this but really I think this is better handled by linters and IDEs by STRONGLY discouraging "import datetime" so people don't get the annoying "'module' object is not callable" or "module 'datetime' has no attribute 'now'" messages. As I said before, this is what I've implemented at work and to us this annoying paper cut has simply gone away. / Anders
On Sat, Feb 02, 2019 at 11:56:47PM -0500, James Lu wrote:
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. [...]
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
You cited articles, but all of them in the context of reading prose, not code. What I was asking where papers describing controlled experiments with a good cross section of programmers with different skill levels against a good cross-section of different project and team sizes. Reading code has some similarity to reading prose, for sure, but let's not forget that code is actually symbolic language more akin to math and logic that "tries" to read like prose. Also, there is the issue of tradition and log embedded traditions for naming constants like these that make such change violate the time-honoured goal of "least-astonishment". Professional programmers usually work/worked previously in several languages, and most of the usual ones follow this style *Ruby:* Ruby style guide as per rubocop says to use SCREAMING_SNAKE_CASE for constants. *Java:* The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.) *C:* Multiple style guides, mostly derived from K&R, for example, the linux kernel style guide is clear: Names of macros defining constants and labels in enums are capitalized. *Javascript: * Also multiple competing style guides, but in general the consensus seems to be that *exported *consts must be capitalized *Go:* The exception here (as usual in Go). Constants should be Camel Case, with lower caps initial for symbols that are not the exported outside the current package, and initial upper case for exported symbols. *R:* The chaos, do whatever the code base you're working with seems to follow as style Those are the languages that most most python programmers are likely to have to work along with python, and as you can see, with the exception of Go and R, most of them have exactly the same Let's also not forget the humongous amount of POSIX constants that are defined as ALL_CAPS, and that we definitely shouldn't be rewriting in another style. Best, Marcos Eliziario Em qua, 30 de jan de 2019 às 19:22, Abe Dillon <abedillon@gmail.com> escreveu:
-- 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/
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.
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.
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.
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 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.)
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.
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.
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.
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 <jpic@yourlabs.org> 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
-- Christopher Barker, PhD Python Language Consulting - Teaching - Scientific Software Development - Desktop GUI and Web Development - wxPython, numpy, scipy, Cython
[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? On Wed, Jan 30, 2019 at 8:00 PM Christopher Barker <pythonchb@gmail.com> wrote:
On Thu, Jan 31, 2019 at 1:05 PM Abe Dillon <abedillon@gmail.com> wrote:
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
On Fri, 4 Jan 2019 at 19:02, Abe Dillon <abedillon@gmail.com> wrote:
I really like the convention. It's nice and clear and absolutely everyone knows what it means. Michael
-- 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
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 <fuzzyman@gmail.com> wrote:
On Fri, Jan 04, 2019 at 06:15:11PM -0600, Abe Dillon wrote:
Code is read more often than it is written. The important question is rarely "can I overwrite random variables?" but is usually "what is the value of this variable right now?". If I see a call like: function(cucumber) I may have no idea what cucumber holds, or where to find its binding. I may have to work hard to determine (1) where it is initially bound; (2) whether or not it has been, or could be, rebound to something else; (3) and what value it holds at the time it is passed to the function. If cucumber is a *variable*, that's kind of unavoidable, its part of what makes programming so ~~frustrating~~ fun and why we have debuggers, tracing and the venerable old technique of inserting print() calls to find out what's going on in our code. But if I see: function(CUCUMBER) that tells me that in idiomatic Python code, CUCUMBER is a constant bound close to the top of the module, and never rebound. -- Steve
On Sat, 5 Jan 2019 at 00:05, Michael Foord <fuzzyman@gmail.com> wrote:
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
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. On Fri, Jan 4, 2019, 2:02 PM Abe Dillon <abedillon@gmail.com wrote:
On Sat, 5 Jan 2019 at 02:46, David Mertz <mertz@gnosis.cx> wrote:
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: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. Use typing hints for constants and tools that support them, and all-caps is no longer needed. An additional sentence that mentions this as an alternative in PEP8 sounds useful. -Mike
On 1/5/19 12:21 PM, Mike Miller wrote:>
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
On Fri, Jan 04, 2019 at 01:01:51PM -0600, Abe Dillon wrote:
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.
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
[Steven D'Aprano]
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]
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]
<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]
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 <steve@pearwood.info> wrote:
On Wed, Jan 30, 2019 at 03:51:22PM -0600, Abe Dillon wrote:
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. [...]
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.
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*.
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
[Steven D'Aprano]
I'm not disputing that,
I mean, you literally wrote: [Steven D'Aprano]
So it sounded a lot like you were. [Steven D'Aprano]
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]
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 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]
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]
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]
I would be able to tell very quickly if I saw those in my IDE whether they were local or global variables. I tend to only import up to the module level (as per Google's style guidelines) specifically so that others know where various variables (like math.pi) come from. In my experience, most constants are configuration that people haven't decided to make configurable yet. I worked at a computer vision lab where the camera had a resolution of 640 x 480 which were originally represented as constants in a lot of our code VERTICAL_RESOLUTION and HORIZONTAL_RESOLUTION , eventually; they became self.horizontal_resolution and self.vertical_resolution. So, my guess is that sigma is either a variable or will become a variable at some point in the future. On Wed, Jan 30, 2019 at 5:59 PM Steven D'Aprano <steve@pearwood.info> wrote:
On Thu, Jan 31, 2019 at 4:59 AM Abe Dillon <abedillon@gmail.com> wrote:
BTW if your IDE or editor supports rich text format styling you can maybe tweak capitalized words to use other font or size. I use UDL in Notepad++ a lot and it can do this - e.g. I use this feature with C++ code to change type names to smaller compact font. Though it requires the list with names of course. So that should be possible in some other Scintilla-based editors i think. AND YES all caps are annoying, especially long ones makes it hard to read, it distracts attention all the time and breaks optical line flow. I need to use enums in Pythonscript plugin quite often and thats how it looks: http://npppythonscript.sourceforge.net/docs/latest/enums.html really annoying. good at least that method wrappers are lowercase. Mikhail
Then by all means, adopt some other convention for your own project's style guides. PEP-8 is not some dictatorial decree from on high that all python be written one way and one way only - heck, even the standard library ignores PEP-8 when convenient, and the committers are loth to merge patches that only correct style issues.
I disagree. They look fine to me, and don't break the flow of reading code for me.
Last I looked, you could not create variables in YouTube comments, so I don't see how that is germane.
Again, you are free to use whatever style guide you choose - an act which in itself is compliant with PEP-8.
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
[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]
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 <steve@pearwood.info> wrote:
knowing this mailing list, i think there was not enough reasons for the no caps case while waiting for the emoji era, i think it stands good Abdur-Rahmaan Janhangeer http://www.pythonmembers.club | https://github.com/Abdur-rahmaanJ Mauritius
On Fri, 4 Jan 2019 at 19:03, Abe Dillon <abedillon@gmail.com> wrote:
Currently PEP-8 prescribes all caps for constants and uses the all cap variable "FILES" as an example in a different section. It also appears to be the defacto-standard for enums (based on the documentation)
I don't think it's necessary to make any breaking changes. Just pep-8 and (of less importance) spurious documentation examples.
If you don't like the recommendation, just don't follow it. It's not like it's set in stone or anything. Personally, I like it and I'm glad it's used on the projects I work on. But you do what suits you. As it's unlikely that the stdlib will stop using caps for constants, changing PEP 8 isn't appropriate (see the first line of the PEP - "This document gives coding conventions for the Python code comprising the standard library in the main Python distribution"). Paul
IMO it's good to have some sort of visual differentiation between constants and normal values. A lot of camelCase-based style guides use a k prefix (e.g. kMyValue), but Python doesn't use it (other than PascalCase for classes). If there were to be an alternative to ALL_CAPS for constants, I guess maybe it'd also be PascalCase? That being said, Dart 2 has dropped ALL_CAPS constants from its style guide, and although everyone's survived just fine, I do somewhat miss being able to immediately be able to see where something is coming from solely from the case. Side note: it seems like ALL_CAPS kind of came from macros being using for constants in C and persisted. -- Ryan (ライアン) Yoko Shimomura, ryo (supercell/EGOIST), Hiroyuki Sawano >> everyone else https://refi64.com/ On Fri, Jan 4, 2019, 1:02 PM Abe Dillon <abedillon@gmail.com 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. On Fri, Jan 4, 2019 at 1:13 PM Ryan Gonzalez <rymg19@gmail.com> wrote:
On Sat, Jan 5, 2019 at 9:59 AM Abe Dillon <abedillon@gmail.com> 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
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.
This is an argument against: - the line length limit (because the IDE should just soft break lines in a super nice way) - explicit “self.” (swift does this with syntax highlighting for example) - CamelCase for classes/types (actually python does a bad job here anyway with int, str, datetime, etc) I’m not saying I disagree but we should be aware that this is the argument. (and as ChrisA rightly points out it’s not fully applicable to constants anyway) / Anders
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? On Fri, Jan 4, 2019 at 2:55 PM Anders Hovmöller <boxed@killingar.net> 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.
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 <rosuav@gmail.com> wrote:
On Sat, Jan 5, 2019 at 10:29 AM Abe Dillon <abedillon@gmail.com> 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 :)
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
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
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:
On Fri, Jan 4, 2019 at 5:41 PM Chris Angelico <rosuav@gmail.com> wrote:
On Sat, Jan 5, 2019 at 11:09 AM Abe Dillon <abedillon@gmail.com> wrote:
The fact that the all-caps convention is used differently (even wrongly) in your current Java employment doesn't really impact this.
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.
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
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 <rosuav@gmail.com> wrote:
Looking at the arguments regarding rendering existing code non-PEP-8-compliant, I think if we were to make this change it should be made in Python 4.0, or whatever the next backwards-incompatible version will be. However, personally I disagree with the fundamental assertion that ALL_CAPS is always ugly. In my humble opinion, when used sparingly (as it is according to PEP 8), they make for a good distinguisher from regular_variables or ClassNames. Since python doesn’t have a “const” or “final” keyword like many strongly typed languages, IDEs would otherwise have a hard time distinguishing between constants and variables. (Although it’s up for debate whether it’s important to developers if this disambiguation is present.) Sent from my iPhone On Jan 4, 2019, at 7:58 PM, Abe Dillon <abedillon@gmail.com> wrote:
On Sat, Jan 5, 2019 at 11:58 AM Abe Dillon <abedillon@gmail.com> 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
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. Your example goes against the convention of using all caps to signify constants and it's a bad design all around. You would be better off with: def get_emote_lits(root = os.path.normpath(__file__ + "/../emotes")): ... # congratulations, you've re-invented the default parameter in a more clunky way! I don't know many APIs built around having you fiddle with module-level variables, it seems like an anti-pattern to me.
If "don't change this externally" is the default, why would we have a naming convention meaning "don't change this externally"?
Modules and Classes and functions typically expose functionality while the purpose of most other objects is to encapsulate state, so it makes sense that attributes would be read/write by default, though some even disagree on that point. I'm not a hard-core functional programming fanatic, so I'm not about to argue that everything should be read-only by default. I also think you're playing dumb to avoid confronting my point: If you found that there was an undocumented module-level attribute in pandas, what would be your initial assumption? If it's not all caps, is it fair game to override it? Can you re-write your emote code so that it's clear that the emote-path variable is part of the API *without* any documentation? How much does all caps really communicate? On Fri, Jan 4, 2019 at 7:16 PM Chris Angelico <rosuav@gmail.com> wrote:
On Sat, Jan 5, 2019 at 1:11 PM Abe Dillon <abedillon@gmail.com> 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
Dnia January 5, 2019 12:09:44 AM UTC, Abe Dillon <abedillon@gmail.com> napisał(a):
It also tells anyone, who is browsing a code, which values come from a spec of some kind (e.g. network protocols, file formats etc.)
which is my default assumption with any variable I didn't declare myself
It has been quite some time since I have learnt to avoid arguments like "I can do it, can everynoe else", because they are false. I like ALL_CAPS and other typographic clues, because I do a lot of integration work and I don't use IDE to browse every file I need to read. -- Łukasz Stelmach z podróży
בתאריך שבת, 5 בינו׳ 2019, 2:10, מאת Abe Dillon <abedillon@gmail.com>
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
I disagree. Changing this in the PEP will make an absurd amount of code which is PEP-8 compliant no longer so. Also, the refactoring may not always be trivial as the lowercase names may already be in use. I'd suggest violating PEP-8 instead of trying to change it.
Changing this in the PEP will make an absurd amount of code which is PEP-8 compliant no longer so.
It depends on how we change it. There's plenty of room to compromise between explicitly mandating all caps and explicitly forbidding all caps. We could simply remove the section that says to use all caps for constants. We could replace that section with a statement that while it's discouraged, it doesn't violate pep8 when used for constants. We could change some of the documentation (especially around enums) to show non-all-caps style is acceptable. etc. On Fri, Jan 4, 2019 at 3:06 PM Bernardo Sulzbach < bernardo@bernardosulzbach.com> wrote:
On 29Jan2019 15:44, Jamesie Pic <jpic@yourlabs.org> wrote:
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 <cs@cskk.id.au>
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 <cs@cskk.id.au> escreveu:
-- 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/
Is it that really obnoxious?
EXTREMELY!
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:
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 <abedillon@gmail.com> wrote:
Capitalizing constants may be slightly harder to read but constants in code are the minority and emphasizing them is precisely the point.
The question I'm trying to get everyone to actually think about: Is the communication of constancy via ALL CAPS so important that it must be in PEP-8 despite the documented harm that all caps does to readability? 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 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. Consider that math.pi and math.e are constants that are not all caps, have you ever been tempted to re-bind those variables? 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. 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? 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. On Wed, Jan 30, 2019 at 2:01 PM Bruce Leban <bruce@leban.us> wrote:
On Thu, Jan 31, 2019 at 8:23 AM Abe Dillon <abedillon@gmail.com> wrote:
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
[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. [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. [ChrisA]
With constants that are taken directly from C, consistency is extremely helpful.
That's fair. I can live with it. The socket module was just an example. There are several examples of all caps that aren't inherited from other sources. If datetime.MINYEAR and datetime.MAXYEAR were datetime.minyear and datetime.maxyear what do you think the consequences would be? Do you really think it's less clear? Do you think timedelta.min, timedelta.max, and timedelta.resolution aren't clear enough? How about string.digits? Should those shout at you that they're constants? Why or why not? [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. [ChrisA]
treat PEP 8 as a guideline
Again, that's not always an option. On Wed, Jan 30, 2019 at 3:41 PM Chris Angelico <rosuav@gmail.com> wrote:
On Thu, Jan 31, 2019 at 9:41 AM Abe Dillon <abedillon@gmail.com> wrote:
You have implied it by making the claim about single words, and then citing references that talk about entire documents.
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.
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.
Again, that's not PEP 8's problem. ChrisA
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. Please cut out the pedantry. It's aggravating and doesn't contribute to the discussion. It comes of as you trying to score "points" in a discussion for being more "technically correct". Example B:
I'm not talking about acronyms OR initialisms **rolls eyes extremely hard**. If you want to discuss whether HttpClient or HTTPClient is more acceptable, go start another thread. I've already responded to this.
This conversation isn't going to go anywhere if you ignore half of what I write.
It's my problem. It's a problem I have to deal with. It's a problem that doesn't need to be a problem. It's a problem that can be solved by modifying PEP-8. I don't even know what you mean by something being "PEP 8's problem". If you can't contribute to the discussion in a meaningful way, then why even respond? On Wed, Jan 30, 2019 at 5:24 PM Chris Angelico <rosuav@gmail.com> wrote:
On Wed, Jan 30, 2019 at 05:41:56PM -0600, Abe Dillon wrote:
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 1/30/2019 6:41 PM, Abe Dillon wrote: <see title> I think continued discussion is pretty useless. 1. Most everything relevant has been said, likely more than once, and 2. The required core-developer support does not exist. PEP 8 was written by Guido with input from other core developers. As Chris said, it defines itself in the opening paragraphs as a "guideline" for the "code in the stdlib". It also disclaims a straightjacket approach. We seldom revise the PEP. Doing so would require initial support from a core developer who garnered more more support. I am not fond of caps either, but not displeased enough to promote the proposal. (What I would like is clarification (from Guido or co-authors) what a 'constant' means in the context.) Abe, if an employer imposes PEP 8 on employees, especially in an overly rigid manner that the PEP discourages, that is an issue between the employer and employees, It is not the problem of Guido and other core developers. -- Terry Jan Reedy
On 30Jan2019 15:22, Abe Dillon <abedillon@gmail.com> wrote:
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."
"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."
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.
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.
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.
Arguing that "nobody has to violate PEP-8" by the mechanism of just dropping recommendations from it isn't very sound, IMO. If your in house style eschews caps for constants, go right ahead. Nobody will stop you. PEP-8 is primarily for the stdlib, where like any shared body of code it is useful to have common style. Plenty of places use PEP-8 as a basis - it is reasonable, and it gets you a fairly complete style guide from day 1. By all means diverge from it on a reasoned basis in your own code or within your own organisation. I do in my personal code: primarily 2 space indentation instead of 4, and my docstring formatting differs as well. And correspondingly, feel free to document your reasons for diverging. They may be universally valid or domain specific; provide such context. But I suspect you'll not get much traction on changing PEP-8 itself in this aspect because the convention is widely liked. Finally, I've worked in ALL CAPS programming environments. BASIC and assembler were traditionally written in all caps. Also FORTRAN. Also Modula-3, at least for its keywords (IF, etc). On the whole I think the world is a better place for being mostly lower case. To such an extent that I wrote a preprocessor for all my Modula-3 to transcribe my personal lower case programmes to upper case for the compiler. But the flip side of being in a mostly lower case world is that having occasional upper case as a standout formatting for particular entities sudden has more value. And that value has been used for constants for a long time with, IMO, some benefit. Cheers, Cameron Simpson <cs@cskk.id.au>
On Wed, Jan 30, 2019, 4:23 PM Abe Dillon <abedillon@gmail.com wrote:
Consider that math.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.
On 1/30/19 6:07 PM, David Mertz 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? (As it looks like ALL_CAPS is here to stay.) -Mike
[Mike Miller]
Another message here reminded me that the datetime classes are not named DateTime like they should be.
There are a few strange conventions in programming that seem almost backwards. In prose, we capitalize proper nouns, but rarely class-type nouns. Bullwinkle is a moose, not bullwinkle is a Moose. It seems the built-ins like int, str, list, dict, etc. get it right, then it's reversed for everything else. [Mike Miller]
There's a Java programming guideline at my workplace that you're supposed to put "final" in-front of pretty much everything because it supposedly makes code easier to reason about. I've since found that the Java community largely supports this idea <http://www.javapractices.com/topic/TopicAction.do?Id=23> (not just my company), which raises the question, "why not make everything default to 'final' and put 'var' or something in-front of the few outliers?". My default assumption for any variable not in the immediate scope is that it's intended to be read-only unless the code I'm reading modifies it. Maybe module-level variables and class-level variables should be all caps if they're NOT constant because then I'd want them to yell at me that they're a potential hazard. Anyway, I thought others might find that to be mildly interesting food for thought. Sorry for bumping this thread again... On Fri, Feb 1, 2019 at 12:59 PM Mike Miller <python-ideas@mgmiller.net> wrote:
On Fri, Feb 1, 2019 at 11:24 AM Abe Dillon <abedillon@gmail.com> 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 2/1/2019 1:59 PM, Mike Miller wrote:
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.
(As it looks like ALL_CAPS is here to stay.)
Yes, I'd say so. Eric
On Fri, Feb 01, 2019 at 02:43:49PM -0500, Eric V. Smith wrote:
On 2/1/2019 1:59 PM, Mike Miller wrote:
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:
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.
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
- 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()?" 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. I have a colleague who likes to point that the future is longer than the past. It's important to keep that perspective. Also Python is still growing so there are more future users than current users. We should take this into account also. / Anders
On Sat, Feb 02, 2019 at 12:06:47AM +0100, Anders Hovmöller wrote:
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.
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
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?
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 Sun, Feb 3, 2019 at 7:57 AM James Lu <jamtlu@gmail.com> wrote:
This kind of readability issue, datetime.now, is an example of what’s contributing to Python’s decline.
Python's decline??? https://pypl.github.io/PYPL.html
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 <steve@pearwood.info> wrote:
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
I know I argued for changing this but really I think this is better handled by linters and IDEs by STRONGLY discouraging "import datetime" so people don't get the annoying "'module' object is not callable" or "module 'datetime' has no attribute 'now'" messages. As I said before, this is what I've implemented at work and to us this annoying paper cut has simply gone away. / Anders
On Sat, Feb 02, 2019 at 11:56:47PM -0500, James Lu wrote:
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. [...]
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
You cited articles, but all of them in the context of reading prose, not code. What I was asking where papers describing controlled experiments with a good cross section of programmers with different skill levels against a good cross-section of different project and team sizes. Reading code has some similarity to reading prose, for sure, but let's not forget that code is actually symbolic language more akin to math and logic that "tries" to read like prose. Also, there is the issue of tradition and log embedded traditions for naming constants like these that make such change violate the time-honoured goal of "least-astonishment". Professional programmers usually work/worked previously in several languages, and most of the usual ones follow this style *Ruby:* Ruby style guide as per rubocop says to use SCREAMING_SNAKE_CASE for constants. *Java:* The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.) *C:* Multiple style guides, mostly derived from K&R, for example, the linux kernel style guide is clear: Names of macros defining constants and labels in enums are capitalized. *Javascript: * Also multiple competing style guides, but in general the consensus seems to be that *exported *consts must be capitalized *Go:* The exception here (as usual in Go). Constants should be Camel Case, with lower caps initial for symbols that are not the exported outside the current package, and initial upper case for exported symbols. *R:* The chaos, do whatever the code base you're working with seems to follow as style Those are the languages that most most python programmers are likely to have to work along with python, and as you can see, with the exception of Go and R, most of them have exactly the same Let's also not forget the humongous amount of POSIX constants that are defined as ALL_CAPS, and that we definitely shouldn't be rewriting in another style. Best, Marcos Eliziario Em qua, 30 de jan de 2019 às 19:22, Abe Dillon <abedillon@gmail.com> escreveu:
-- 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/
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.
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.
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.
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 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.)
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.
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.
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.
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 <jpic@yourlabs.org> 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
-- Christopher Barker, PhD Python Language Consulting - Teaching - Scientific Software Development - Desktop GUI and Web Development - wxPython, numpy, scipy, Cython
[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? On Wed, Jan 30, 2019 at 8:00 PM Christopher Barker <pythonchb@gmail.com> wrote:
On Thu, Jan 31, 2019 at 1:05 PM Abe Dillon <abedillon@gmail.com> wrote:
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
On Fri, 4 Jan 2019 at 19:02, Abe Dillon <abedillon@gmail.com> wrote:
I really like the convention. It's nice and clear and absolutely everyone knows what it means. Michael
-- 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
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 <fuzzyman@gmail.com> wrote:
On Fri, Jan 04, 2019 at 06:15:11PM -0600, Abe Dillon wrote:
Code is read more often than it is written. The important question is rarely "can I overwrite random variables?" but is usually "what is the value of this variable right now?". If I see a call like: function(cucumber) I may have no idea what cucumber holds, or where to find its binding. I may have to work hard to determine (1) where it is initially bound; (2) whether or not it has been, or could be, rebound to something else; (3) and what value it holds at the time it is passed to the function. If cucumber is a *variable*, that's kind of unavoidable, its part of what makes programming so ~~frustrating~~ fun and why we have debuggers, tracing and the venerable old technique of inserting print() calls to find out what's going on in our code. But if I see: function(CUCUMBER) that tells me that in idiomatic Python code, CUCUMBER is a constant bound close to the top of the module, and never rebound. -- Steve
On Sat, 5 Jan 2019 at 00:05, Michael Foord <fuzzyman@gmail.com> wrote:
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
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. On Fri, Jan 4, 2019, 2:02 PM Abe Dillon <abedillon@gmail.com wrote:
On Sat, 5 Jan 2019 at 02:46, David Mertz <mertz@gnosis.cx> wrote:
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: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. Use typing hints for constants and tools that support them, and all-caps is no longer needed. An additional sentence that mentions this as an alternative in PEP8 sounds useful. -Mike
On 1/5/19 12:21 PM, Mike Miller wrote:>
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
On Fri, Jan 04, 2019 at 01:01:51PM -0600, Abe Dillon wrote:
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.
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
[Steven D'Aprano]
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]
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]
<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]
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 <steve@pearwood.info> wrote:
On Wed, Jan 30, 2019 at 03:51:22PM -0600, Abe Dillon wrote:
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. [...]
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.
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*.
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
[Steven D'Aprano]
I'm not disputing that,
I mean, you literally wrote: [Steven D'Aprano]
So it sounded a lot like you were. [Steven D'Aprano]
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]
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 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]
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]
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]
I would be able to tell very quickly if I saw those in my IDE whether they were local or global variables. I tend to only import up to the module level (as per Google's style guidelines) specifically so that others know where various variables (like math.pi) come from. In my experience, most constants are configuration that people haven't decided to make configurable yet. I worked at a computer vision lab where the camera had a resolution of 640 x 480 which were originally represented as constants in a lot of our code VERTICAL_RESOLUTION and HORIZONTAL_RESOLUTION , eventually; they became self.horizontal_resolution and self.vertical_resolution. So, my guess is that sigma is either a variable or will become a variable at some point in the future. On Wed, Jan 30, 2019 at 5:59 PM Steven D'Aprano <steve@pearwood.info> wrote:
On Thu, Jan 31, 2019 at 4:59 AM Abe Dillon <abedillon@gmail.com> wrote:
BTW if your IDE or editor supports rich text format styling you can maybe tweak capitalized words to use other font or size. I use UDL in Notepad++ a lot and it can do this - e.g. I use this feature with C++ code to change type names to smaller compact font. Though it requires the list with names of course. So that should be possible in some other Scintilla-based editors i think. AND YES all caps are annoying, especially long ones makes it hard to read, it distracts attention all the time and breaks optical line flow. I need to use enums in Pythonscript plugin quite often and thats how it looks: http://npppythonscript.sourceforge.net/docs/latest/enums.html really annoying. good at least that method wrappers are lowercase. Mikhail
Then by all means, adopt some other convention for your own project's style guides. PEP-8 is not some dictatorial decree from on high that all python be written one way and one way only - heck, even the standard library ignores PEP-8 when convenient, and the committers are loth to merge patches that only correct style issues.
I disagree. They look fine to me, and don't break the flow of reading code for me.
Last I looked, you could not create variables in YouTube comments, so I don't see how that is germane.
Again, you are free to use whatever style guide you choose - an act which in itself is compliant with PEP-8.
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
[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]
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 <steve@pearwood.info> wrote:
knowing this mailing list, i think there was not enough reasons for the no caps case while waiting for the emoji era, i think it stands good Abdur-Rahmaan Janhangeer http://www.pythonmembers.club | https://github.com/Abdur-rahmaanJ Mauritius
On Fri, 4 Jan 2019 at 19:03, Abe Dillon <abedillon@gmail.com> wrote:
Currently PEP-8 prescribes all caps for constants and uses the all cap variable "FILES" as an example in a different section. It also appears to be the defacto-standard for enums (based on the documentation)
I don't think it's necessary to make any breaking changes. Just pep-8 and (of less importance) spurious documentation examples.
If you don't like the recommendation, just don't follow it. It's not like it's set in stone or anything. Personally, I like it and I'm glad it's used on the projects I work on. But you do what suits you. As it's unlikely that the stdlib will stop using caps for constants, changing PEP 8 isn't appropriate (see the first line of the PEP - "This document gives coding conventions for the Python code comprising the standard library in the main Python distribution"). Paul
participants (29)
-
Abdur-Rahmaan Janhangeer -
Abe Dillon -
Alex Walters -
Anders Hovmöller -
Ben Rudiak-Gould -
Bernardo Sulzbach -
Bruce Leban -
Cameron Simpson -
Chris Angelico -
Christopher Barker -
Dan Sommers -
David Mertz -
Elazar -
Eric Fahlgren -
Eric V. Smith -
Ivan Levkivskyi -
James Lu -
Jamesie Pic -
Marcos Eliziario -
Michael Foord -
Mike Miller -
Mikhail V -
Noah Simon -
Paul Moore -
Ryan Gonzalez -
Steve Barnes -
Steven D'Aprano -
Terry Reedy -
Łukasz Stelmach