[Tutor] _ vs. _name vs. __name vs. name_ vs. __name__ usages

[Ben Finney]

boB Stepp <robertvstepp at gmail.com> writes:

> From my understandings to date:
>
> 1) A single underscore is used conventionally for a "throw-away"
> variable, such as a loop index for which the index value is not
> actually used in a subsequent calculation.

That accurately describes common usage. But it's important to also know
that ‘_’ has numerous conflicting common usages (including a widely-used
text translation function).

Less common, but IMO much more preferable for “don't actually want this
value but need to bind something to it”, is the convention ‘__’ as a
name::

    for (__, important_value) in sequence_of_tuples:
        ...

The name ‘__’ doesn't AFAIK have conflicting usages (therefore more
strongly connoting this meaning), is pretty easy to type and much easier
to spot than a single underscore.

> 2) _name is used inside class methods to indicate that the
> programmer's intention is that this name should only be accessed
> internally by that particular class.

Not so much “inside class methods”; rather, the names are on attributes
of a class (or module or, sometimes, function).

This is the convention for “even if you can see this attribute, it is an
implementation detail, not part of the public API for this class,
anything might change about this in future revisions”.

With no leading underscore, the implicit promise is that the name is a
published API for the code, and can be relied on to keep the same name
and behaviour in future revisions of the code.

> 3) __name invokes Python's name mangling mechanism. The intent of this
> usage is to not allow subclasses of the class containing __name to
> access this name, and to add additional emphasis to future users of my
> code that this name is meant to be strictly hands-off.
>
> […] it seems to me that one would normally be able to use the
> simpler _name construction

Right. I've felt any need to use this in my Python programming career;
the distinction between “public API” (‘foo’) versus “implementation
detail” (‘_foo’) is plenty.

> 4) name_ is used when one is "forced" to use one of Python's reserved
> words as a name.

Yes. It's a last resort, IMO, but a valuable one; and the only damage is
to readability (difficult to distinguish when reading quickly).

> it seems that normally (4) should never be needed, though I have a
> feeling that I have seen something in tkinter recently that suggests
> some exceptions, but I cannot (yet) bring it to mind.

The Python keywords and built-in object names include some obvious,
common words. This is a clear benefit, but it can also cause a clash
when choosing your own names: some of the best ones are already taken.

I've seen this used to name ‘assert_’, ‘file_’, and the like.

> 5) __name__ is meant to be used only by the creators of Python for
> their special built-in methods, such as __init__, __new__, etc.
>
> […] surely I should never violate this one?  It seems that in
> some future edition of Python they might add any particular __name__
> that I might try to use presently in their future version of Python
> (however miniscule that possibility might actually be).

Yes. Never name anything with this ‘__foo__’ style unless Python already
will treat it specially, and your intention is to invoke that special
treatment by Python.

This convention is violated too often in third-party code for names that
don't have any special significance to Python, leading to needless
confusion about how special a newly-encoutered name really is. All the
ones I've seen in third-party code would always be improved for clarity
by choosing a normal ‘foo’ or ‘_foo’ name.

> Are my understandings above correct or flawed?

I hope that helps.

-- 
 \          “It's dangerous to be right when the government is wrong.” |
  `\                                   —Francois Marie Arouet Voltaire |
_o__)                                                                  |
Ben Finney