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

[Abe Dillon]

>
> >> I will often use a module-level constant
> >> for a file or path name; within the module, it is deliberately treated
> >> as a constant, but if you import the module somewhere else, you could
> >> reassign it before calling any functions in the module, and they'll
> >> all use the changed path.
> >
> > Do you communicate that API through the variable name alone? How so? I
> would assume any module-level variables are not to be modified unless there
> was documentation stating otherwise. You really don't need a obnoxious
> shouty convention to tell people not to change things.
> >
> Yeah. By naming it in all caps. That's exactly how that's communicated.
> Example:
> https://github.com/Rosuav/shed/blob/master/emotify.py#L6
> By default, it's calculated from __file__, but if an external caller
> wants to change this, it's most welcome to. Since it's in all-caps,
> you don't have to worry about it being changed or mutated during the
> normal course of operation.


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

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

My whole point is that the thing that all-caps communicates: "you shouldn't
change this", is the default assumption for pretty-much every variable you
encounter, so it's really not that helpful. If you snooped around and found
that the pandas module had a variable called "cucumber" that doesn't appear
in the docs at all, would you assume that it's kosher to assign a value to
pandas.cucumber?

Well, then, no, that's not "it's up to you". Something mandated by a
> style guide is not a tool in your toolbox

Yes, and PEP-8 being the de-facto style guide for Python is the starting
place for many mandatory Python style guides, which is why I'm arguing to
remove the all caps BS from it.

But if you leave that part out, then yes, 'final' becomes a
> tool that you may use if you wish, or ignore if you wish.

Do you think we should add "final", "private", etc. to Python? The point
was that such things are clearly not necessary, yet if you suggest removing
them, you'll get the exact same "might as well keep it in the toolbox"
reaction or worse.

The code style guides at my work aren't unique, they've been recycled for
decades. It's like day-light savings time. People have some vague notion
that it might have been a good idea in the past and now we just keep going
through the motions even though it makes no sense. You just can't shake the
notion that somehow, typing in all caps is a great way to convey
information in code, when it's an extremely obnoxious means of conveying
information in any other written form.

On Fri, Jan 4, 2019 at 6:23 PM Chris Angelico <rosuav at gmail.com> wrote:

> On Sat, Jan 5, 2019 at 11:09 AM Abe Dillon <abedillon at gmail.com> wrote:
> >>
> >> Just to be clear here: you're trying to say that the ALL_CAPS_NAME
> >> convention is unnecessary, but you don't use constants. That kinda
> >> weakens your argument a bit :)
> >
> >
> > Just to be clear, I'm currently working in a Java shop where the
> code-styles are to use all caps for constants, enums, and class-level
> variables. Most classes in our code base declare a class-level "LOG" or
> "LOGGER" object. I've found that completely unnecessary. A simple "log"
> works just fine. I've never been tempted to write over it. It would be
> impossible in Java anyway since the guidelines are to declare everything
> "final" (yes... shoot me) anyway. I helped one of the higher-ups in the
> company write a Python script and he found the lack of straight-jacket
> harnesses extremely distressing. How could you write code without "final"?
> or "private"? or type checking?! You have to use consistent white space?!?!
> >
> > It's all Stockholm syndrome.
>
> The fact that the all-caps convention is used differently (even
> wrongly) in your current Java employment doesn't really impact this.
>
> >> The whole point of the all-caps globals is to tell you a lot about what
> they are.
> >
> >  A lot? The only thing it canonically tells you is to not modify it
> which is my default assumption with any variable I didn't declare myself
> and also impossible to do in the case of enums.
> >
> >> I will often use a module-level constant
> >> for a file or path name; within the module, it is deliberately treated
> >> as a constant, but if you import the module somewhere else, you could
> >> reassign it before calling any functions in the module, and they'll
> >> all use the changed path.
> >
> > Do you communicate that API through the variable name alone? How so? I
> would assume any module-level variables are not to be modified unless there
> was documentation stating otherwise. You really don't need a obnoxious
> shouty convention to tell people not to change things.
> >
>
> Yeah. By naming it in all caps. That's exactly how that's communicated.
> Example:
>
> https://github.com/Rosuav/shed/blob/master/emotify.py#L6
>
> By default, it's calculated from __file__, but if an external caller
> wants to change this, it's most welcome to. Since it's in all-caps,
> you don't have to worry about it being changed or mutated during the
> normal course of operation.
>
> >> It's up to you whether you actually use the all-caps convention in
> >> your own code or not, but IMO it is an extremely useful convention to
> >> have in the toolbox, and should be kept.
> >
> > My boss would say:
> >>
> >>  It's up to you whether you actually use final in
> >> your own code or not, but IMO it is an extremely useful tool to
> >> have in the toolbox, and should be kept. (and also you have to use it
> because it's in the style guide)
> >
>
> Well, then, no, that's not "it's up to you". Something mandated by a
> style guide is not a tool in your toolbox, it's a requirement of the
> project. But if you leave that part out, then yes, 'final' becomes a
> tool that you may use if you wish, or ignore if you wish. (Personally,
> I would ignore that one, with the exception of "public static final"
> as an incantation for "class-level constant".)
>
> ChrisA
> _______________________________________________
> Python-ideas mailing list
> Python-ideas 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/20190104/522e6c7c/attachment-0001.html>