[Python-ideas] AMEND PEP-8 TO DISCOURAGE ALL CAPS

[Abe Dillon]

[Steven D'Aprano]

> > ALL_CAPS_IS_OBNOXIOUS
> >
> > It destroys the visual flow of code
> Does it? This claim doesn't ring true to me. To me, "visual flow of
> code" is the way it flows down and across the page, not the shape of the
> individual words.


It does. Your field of vision is two-dimensional and multi-scale.
Your visual system uses lots of queues to determine what to focus on and
how to interpret it.
So both the way code flows down the page and the shape of individual words
matter to readability:

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

[Steven D'Aprano]

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


It's not precisely the same to me. My eye is drawn heavily to "dup2" in the
latter.
In the former my eye isn't drawn strongly to anything in particular. It's
slightly drawn to the asterisk.

I suppose I should clarify that when I talk about "visual flow" I mean how
my eye is drawn around the media.

[Steven D'Aprano]

> I can immediately tell that unlike spam and eggs, FILENAME ought to be a
> global constant, which is a valuable hint that I can probably find the
> value of FILENAME by looking at the top of the module, and not worry
> about it being rebound anywhere else.


<control> + f  "filename ="
You can tell if its rebound anywhere by the number of matches.

[Steven D'Aprano]

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


None. You don't need one.

[Steven D'Aprano]

> We can (usually) accurately
> recognise modules, classes and functions from context, but we can't do
> the same for constants.


What are you basing that claim on? I can tell that  math.pi, string.digits,
and timedelta.resolution are constants just fine.



On Fri, Jan 4, 2019 at 9:42 PM Steven D'Aprano <steve at pearwood.info> wrote:

> On Fri, Jan 04, 2019 at 01:01:51PM -0600, Abe Dillon wrote:
>
> > I keep coming back to this great video <https://vimeo.com/74316116>
> about
> > coding style, and one point in particular rings true to me:
> > ALL_CAPS_IS_OBNOXIOUS
> >
> > It destroys the visual flow of code
>
> Does it? This claim doesn't ring true to me. To me, "visual flow of
> code" is the way it flows down and across the page, not the shape of the
> individual words.
>
> To me, long lines spoil the visual flow of code (especially if they are
> long enough that I have to scroll horizontally to see the end).
>
> To me, sudden blocks of unexpected indentation spoil the visual flow of
> code.
> (Fortunately, this is rare in Python.)
>
> I've looked over code in the standard library, my own code, and
> third-party libraries, and I don't see that the choice of name disrupts
> the flow of code, whether it is written in CamelCase of lowercase or
> ALLCAPS or even rAnSOmenOTecAse. (Although I admit that last one is
> quite hard to read...)
>
> I have a bunch of code written in RPL for the HP-48GX calculator, and
> the convention there is that nearly everything is written in allcaps.
> Here's an equivalent function to Python's divmod():
>
>     << DUP2 DIV SWAP OVER * ROT SWAP - >>
>
> The flow is fine if you know how to read reverse Polish notation ("Yoda
> speak"). It flows from left to right, and top down, same as English.
> Only the word order is different. The flow would be precisely the same
> if it were written like this:
>
>     << dup2 div swap over * rot swap - >>
>
> Where RPL does suffer from the lack of visual flow is the lack of
> structure to the code. In Python terms, it would be as if we wrote:
>
>     def function(): if condition: for x in sequence: do_this()
>     do_that() endfor else: do_something_else() endif
>
> Ouch.
>
> The bottom line is, I don't agree that the visual flow of code is
> negatively affected, or affected at all, by the shape of individual
> words in the code.
>
>
> > and for what? To signify a global,
> > constant, or Enum? Is that really so important? I don't think so.
>
> I think the convention is useful, of moderate importance, and I think
> Python code would be ever-so-slightly harder to understand without it.
>
> I rarely, if ever, use allcaps for constants defined and used in a
> single function, but that's because my functions are typically short
> enough that you can fit the entire function on screen at once and tell
> that the name is defined once and never re-bound, hence a constant.
>
> Where the naming convention really makes sense is for module-level
> constants, where the initial binding is typically separated from the
> eventual use by a lot of time and space, I think it is useful to have a
> simple naming convention to distinguish between variables and constants.
> When I see this in the middle of a function:
>
>     def foo():
>         ...
>         process(spam, FILENAME, eggs, ...)
>         ...
>
> I can immediately tell that unlike spam and eggs, FILENAME ought to be a
> global constant, which is a valuable hint that I can probably find the
> value of FILENAME by looking at the top of the module, and not worry
> about it being rebound anywhere else. So yes, having a naming convention
> for constants is useful.
>
> And FILENAME is much better than cfilename or kfilename or
> constant_filename_please_dont_rebind_ok_thx *wink*
>
> What naming convention would you suggest for distinguishing between
> constants and variables?
>
> I suppose one might argue that we don't need to care about the semantics
> of which names are variables and which are constants. In fairness, we
> cope quite well with modules, classes and functions being effectively
> constants and yet written in non-allcaps.
>
> But on the other hand, we generally can recognise modules, classes and
> functions by name and usage. We rarely say "process(module)", but we
> might say "process(module.something)". Classes have their own naming
> convention. So the analogy between global constants which don't use the
> allcaps convention (namely modules, classes and functions) and global
> constants which do is fairly weak. We can (usually) accurately
> recognise modules, classes and functions from context, but we can't do
> the same for constants.
>
>
> > Currently PEP-8 prescribes all caps for constants
> > <https://www.python.org/dev/peps/pep-0008/#constants> and uses the all
> cap
> > variable "FILES" as an example in a different section.
> > <https://www.python.org/dev/peps/pep-0008/#when-to-use-trailing-commas>
> It
> > also appears to be the defacto-standard for enums (based on the
> > documentation <
> https://docs.python.org/3/library/enum.html#creating-an-enum>
> > )
>
> That's because the typical use for enums is as constants. If I had a
> *variable* which merely held an enum, I wouldn't use allcaps:
>
>     # No! Don't do this!
>     for MYENUM in list_of_enums:
>         if condition(MYENUM):
>              MYENUM = something_else()
>         process(MYENUM)
>
>
>
> --
> Steve
> _______________________________________________
> Python-ideas mailing list
> Python-ideas at python.org
> https://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20190130/9326733a/attachment-0001.html>