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
_______________________________________________
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/
