[Python-ideas] AMEND PEP-8 TO DISCOURAGE ALL CAPS
cs at cskk.id.au
Wed Jan 30 17:07:09 EST 2019
On 30Jan2019 15:22, Abe Dillon <abedillon at 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?
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:
"From a design perspective, All Caps can be useful for labels, logos and
menus where your message doesn't involve reading large sections of
"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
"That doesn’t mean you shouldn’t use caps. Just use them judiciously.
Caps are suitable for headings shorter than one line (e.g., “Table of
Contents”), headers, footers, captions, or other labels. Caps work at
small point sizes. Caps work well on letterhead and business cards."
>I've gotten many responses that seem like a knee-jerk reaction in favor of
>the status quo. I get the sense people "like" all caps because they've been
>conditioned to believe it conveys important information, but they haven't
>taken the time to really consider how valid that belief is.
You may find that (a) plenty of us have been using this convention for a
very long time and (b) we find it useful and (c) it doesn't cause us any
trouble. Also, cross language conventions have additional value. Don't
think we've never thought about its value.
>Consider that math.pi and math.e are constants that are not all caps, have
>you ever been tempted to re-bind those variables?
No, but "e" and "pi" are _conventionally_ spelt in lowercase in prose.
Which is why they are lower case in the math module. As with the socket
example below, here they match their casing in their source context
And regarding temptation to change these, there's a very old humorous
anecdote about FORTRAN, in that like Python it has no constants: you can
change "PI", for example to 3. Badness ensues. Nobody is arguing that we
should consider math.e or math.pi sane things to modify because the
Python module uses lower case for their names.
>Do you seriously worry
>that those variables are going to be re-bound by other code? Functions and
>classes are essentially constants that aren't all caps, yet nobody gets
>confused about whether or not to re-bind those, or if other code will
You'll notethat in Python, assigning to a name in a function _causes_
that name to be locally scoped. This avoids a whole suite of accidents.
And we rebind names bound to functions all the time, not just for monkey
patching but also when we pass functions as callbacks. Python function
names are _not_ functions, they're _references_ to functions.
>If socket.AF_INET6 were socket.af_inet6 would you consider re-binding that
>variable? Would you be worried that other code will re-bind it? Can you
>measure the value of the information conveyed by all-caps? Are you so sure
>that it's as important as you think?
It is important for 2 reasons: it adhere's to the well established
convention of a constant being in all caps, which has value in itself
(adherence to the convention) _and_ it is spelled exactly like the
AF_INET6 constant from the C socket API, of which Python's socket module
is essentially a shim with some additional utility facilities.
>I've gotten a lot of responses like, "If you don't like it just ignore
>PEP-8, it's not mandatory".
>A) It is mandatory in many cases.
>B) We could just as easily NOT prescribe all caps in PEP-8 but still allow
>it. In other words: you can use all caps if you want to but it's not
>mandatory or in PEP-8. I would like to discourage its use, but we don't
>have to go so far. That way nobody has to violate PEP-8.
Arguing that "nobody has to violate PEP-8" by the mechanism of just
dropping recommendations from it isn't very sound, IMO.
If your in house style eschews caps for constants, go right ahead.
Nobody will stop you. PEP-8 is primarily for the stdlib, where like any
shared body of code it is useful to have common style.
Plenty of places use PEP-8 as a basis - it is reasonable, and it gets
you a fairly complete style guide from day 1. By all means diverge from
it on a reasoned basis in your own code or within your own organisation.
I do in my personal code: primarily 2 space indentation instead of 4,
and my docstring formatting differs as well.
And correspondingly, feel free to document your reasons for diverging.
They may be universally valid or domain specific; provide such context.
But I suspect you'll not get much traction on changing PEP-8 itself in
this aspect because the convention is widely liked.
Finally, I've worked in ALL CAPS programming environments. BASIC and
assembler were traditionally written in all caps. Also FORTRAN. Also
Modula-3, at least for its keywords (IF, etc). On the whole I think the
world is a better place for being mostly lower case. To such an extent
that I wrote a preprocessor for all my Modula-3 to transcribe my
personal lower case programmes to upper case for the compiler.
But the flip side of being in a mostly lower case world is that having
occasional upper case as a standout formatting for particular entities
sudden has more value. And that value has been used for constants for a
long time with, IMO, some benefit.
Cameron Simpson <cs at cskk.id.au>
More information about the Python-ideas