[Python-ideas] PEP 8 update on line length

[Steven D'Aprano]

On Tue, Feb 19, 2019 at 11:38:04AM +0100, Nicolas Rolin wrote:

> I understand that the writer wants to have shorter names, but why would I
> want more ambigious names as a reader ?
> How would you rename number_of_pages_in_current_section such that the
> reader is not left wondering what does this variable represents ?

Excellent question! Note that I didn't say that long names are 
*necessarily* a problem, only that they could be.

I would start by reading the code and asking two questions:

1. Does the name really need to specify that it is the number of pages 
in the *current* section?

Unless you have multiple such variables:

    number_of_pages_in_current_section
    number_of_pages_in_previous_section
    number_of_pages_in_next_section

the chances are very good that "in_current_section" is pointless 
information that the reader will infer from context:

    for section in sections:
        number_of_pages = len(section)

2. Do you really need such a verbose name spelled out in full?

Instead of "number_of_pages", perhaps "num_pages" is enough. If it is 
obvious from context, perhaps even "num" or even "n" is enough.

If you dislike such standard abbrevations, how about "pagecount"?

Short names are not necessarily ambiguous, and long names are 
not necessarily clear:

    process(the_current_thing_we_are_processing_right_now)

is no less ambiguous or any more clear than:

    process(thing)

In a well-written function that isn't too long, we ought to be able to 
find the definition of any local variable no more than half a page away.
Local variables are usually far more limited in their scope and lifetime 
and the need for them to be self-documenting is correspondingly reduced.

Insisting that *every* name must be meaningful *in isolation* is an 
over-reaction to poor quality code. Typically we read code in context: 
we can see the rest of the function and the definition of the variable 
is only a handful of lines away.

The interpreter doesn't care what you call your variables, names are 
purely comments for the reader. It isn't true that the more comments 
the better, and the same applies to naming:

- Just as comments can lie, so can names. I expect we've all read code 
where the names are actively misleading:

    mylist = {key: value}

- Comments shouldn't simply repeat the obvious meaning of the code:

    x += 1  # add 1 to x

and neither should variable names. If meaning can be inferred from the 
obvious meaning of the code, the need to spell out the meaning in full 
is reduced. (See my example above of number_of_pages.)

- When writing comments we should eschew sesquipedalian loquaciousness

    x += 1  # increment the value of the variable x by the successor integer to the additive identity of Z

and we ought to do the same for variable names.


-- 
Steven