The task is to invent names for things

[dn]

On 29/10/2021 07.07, Stefan Ram wrote:
>   The name should not be "optimized" for a certain use case
>   (as for the use in an if expression) only. "We", "have",
>   and "any" carry little information. A name should pack as
>   much information as possible in as least characters as
>   possible. So, for me, it'd be something like:

Although, does that not imply that "pack[ing]...information" is primary,
and "least characters..." secondary?

How else to define "readability" (wrt 'names')?


> if word_count:

Yes, but this does open the door to the 'gotchas' of truthiness, ie
there ain't no such thing as a free lunch/"silver bullet".

Whereas, names such as:

is_valid
words

help to imply a boolean and a collection, resp. (cf the micro-softy way
of imposing the language-technicalities over naming-readability, eg

bValid


Thereafter, to counter the idea of not having too many names, there may
be an argument for setting-up one's data to be able to code:

if is_valid:
    while word_count:
       # pop word from words and do something...

so now we have a data-set which includes:

words: a collection, eg arriving to us from some input
word: one item from words, isolated for processing
word_count: a convenient expression of len( words )
is_valid: an indicator that the words received are ready for our process

(not that I 'like' "is_valid" but need a specific context to improve that)

The "is_" prefix appeals to me because it is so English-like (dare I say
COBOL-like?) that readability is in no doubt. At the same time, whilst
it could be considered and 'extra' name/extra-effort, it adds precision
to the logic.

YMMV!
Indeed some may wish to argue that the data-set includes unnecessary
verbiage, and that this in-and-of-itself might contribute to
cognitive-overload...

import this


>> So, the obvious solution is to ask the language, like Python, to allow
>> variables that are synonyms.
> 
>   Programs already have too many names in them. 
>   There is no need to add even more, especially
>   when they are equivalent, and the average human can
>   only hold 7 ± 2 objects (like names) in his short-
>   term memory.

+1

aka "cognitive overload"

@Martin's term is "naming paralysis", which fits as a component of
"analysis paralysis", cf 'let's get on with it'!

(which summed-up how I felt abstracting and refactoring a function this
morning - dithering and vacillating like I couldn't decide between
chocolate cake or chocolate pudding...)

Which point, when referred to synonym variables, gives the optimal
answer: "both" (cake and pudding!)

When you think about it, passing values to functions, ie an argument
becomes a parameter, that can be considered a form of synonym.

(and (before someone disappears off on another unintended tangent) some
circumstances where it is not!)


>> really good names often end up being really long names
> 
>   If they are really long, they are not really good, 
>   /except/ when they have a really large scope.
> 
>   Names for a small scope can and should be short,
>   names for a large scope may be longer.

Interesting! Surely as something becomes more specific, there is more
meaning and/or greater precision to be embedded within the name. Thus:

operator

assignment_operator
walrus_operator


>   Some very short names have traditional meanings
>   and are ok when used as such:
> 
> for i in range( 10 ):

For historical (?hysterical) reasons I find myself agreeing with this.
(in FORTRAN any variable beginning with the letters "I" through "N" was
regarded as an integer - all others being real/floating-point - thus, it
is a familiar idiom.

That said, this form of for-loop is reminiscent of other languages which
use "pointers" to access data-collections, etc, and keep track of where
to logic is within the process using "counters" - none of which are
necessary in pythonic for-loops.

Accordingly, there is an argument for using:

for ptr in range( 10 ):
for ctr in range( 10 ):

(or even the complete word, if that is the functionality required)

The above allowing for the fact that I have my own 'set' of 'standard
abbreviations' which are idiomatic and readable to me (!). One of which is:

for ndx in range( 10 ):

This abbreviation originated in the days when variable-names had to be
short. So, one tactic was to remove vowels*. Once again, more readable
(to me) than "i", but possibly less-than idiomatic to others...

That said, watching a video from EuroPython 2021, I was amused to see:

for idx in range( 10 ):

and doubly-amused when I experimented with the idea as-presented and
'copied' the code by 'translating' his "idx" into the English "index",
and whilst typing into my own REPL, cogno-translated the thought into my
own "ndx" expression.


Now, I don't know if the EuroPython author uses "idx" because that
relates somehow to his home-language. However, if we analyse such
abbreviations, their writing is a personal exercise. Whereas,
measuring/assessing "readability" involve neither "writing" nor
"personal" at its core. Thus, if there is a "jargon" abbreviation which
is readily understandable, is it so 'bad' just because it is not a
complete (English) word?

Until I spent more (?too much) time with folk who formed their Style
Guides as super-sets of PEP-008, I didn't worry too much about these
abbreviations. People 'here' are amongst those who dislike(d) my use of:

idNR - id = identification (?), number (NB suffix)
NUMwords = number in/len() of a collection (NB prefix)
arrayPTR = pointer to specific member within array


The interesting thing about some of these (aside from PEP-008) is that
they are very historial - as above. Accordingly, it is 'the youngsters'
who object more vociferously (aside from pedants, like trainers, er,
cough, splutter). Yet, until a few years ago I would not have understood
"OMG" and similar 'text-isms' that have escaped into the real-world from
cell-phones. Yet, asking (a youngster) what (s)he means will
stereotypically involve a shrug or eye-roll (patent-pending) indicating
that I should not need to ask because 'everyone' knows!

(OK, so am I allowed to give you a few PTRs about politesse?)


NB I find that 'modern IDEs' and sundry plug-ins are possibly more
responsible for making me PEP-008-compliant than any human(s). The
nagging splatters of queries and criticisms are even less
politically-correct than aforementioned ageist youngsters!


>   . And, as a "golden rule" for refactoring, I'd say:
>   When you see:
> 
> i = 0 # word count
> 
>   , then remove the comment and rename "i" to "word_count"!

Yes, a beautiful illustration of why comments can cause more damage than
they should (theoretically) be helping us, readers, avoid...

Two for the price of one: criticising the choice of name, and the choice
of comment!



* see also written Classical Arabic
-- 
Regards,
=dn