pylint -- should I just ignore it sometimes?

[Seebs]

Another situation in which I needed to disable such kind of warnings
is while working with graphics modules.
I often use variable names such as x, y, z for coordinates, or r,g,b for colors.
Would longer names make the reader's life easier?

Interesting point. Which is really easier to read:

x, y, z = p.nextpoint()

xCoordinate, yCoordinate, zCoordinate = polygon.nextPointCoordinates()

-s

 

[Martin P. Hellwig]

Interesting point. Which is really easier to read:

x, y, z = p.nextpoint()

xCoordinate, yCoordinate, zCoordinate = polygon.nextPointCoordinates()

-s

Although intuitively I would say the shorthand, however that is
depending on the context being me knowing at least the basics of 3d
spaces and having the pre-warning that you are going to mention
something with either coordinates or colours.

Take away this pre-information, as you would when first reading an
application, and all of the sudden the latter would be much clearer to
the fellow programmer.

 

[Jean-Michel Pichavant]

except ValueError, e:

Use meaningful names, this is so important. 'e' is not meaningful.
'exception' would be slighly better.

While I agree with everything else you had to say, I have to take
exception to this comment [pun intended].

"e" as a short name for a generic exception instance is perfectly
reasonable, like:

i, j, k for an index, or a loop variable
e.g. for i in range(100)
n for some other integer variable
s for a string
x for a float, or an arbitrary sequence object
e.g. [x.spam() for x in some_sequence]

and similar.

The last example is very instructive. What do you gain by racking your
brain for a "more meaningful" name instead of x? The obvious
alternatives, "obj" or "item", are equally generic as "x", they don't add
any further information. And how much information do you need? It's easy
to parody:

[some_sequence_item.spam() for some_sequence_item in some_sequence]

The very shortness of the name is valuable because it reduces the *human*
parsing time in reading, and there is no cost because the conventions are
so familiar. The convention of "for i in ..." says "this is a loop over
an integer" so strongly, that I would argue that "for index in ..." would
actually *delay* comprehension.

Furthermore, the use of a single letter cues the reader that this
variable isn't notable -- there's nothing unusual or unconventional about
it, or it isn't the important part of the algorithm, or that its scope is
severely limited. For instance, consider the classic example of
exchanging two variables in Python:

a, b = b, a

versus:

thing, other_thing = other_thing, thing

The first example puts the emphasis on the *technique*, not the
variables. The second obscures it behind needlessly longer but still
generic names.

You are absolutely right to insist on meaningful variable names. Where
you go wrong is to assume that single letter names can't be meaningful.

You are using meaningless example without any context, for sure you
won't find a proper meaningful name.
Let me quote the paper I linked in the previous post:

list1 = []
for x in theList:
if x[0] == 4:
list1 += x;
return list1

compare it to:

flaggedCells = []
for cell in theBoard:
if cell[STATUS_VALUE] == FLAGGED:
flaggedCells += cell
return flaggedCells

There is another important point: the time where code size matters is over. Now we have the opportunity to write better structured english and that is priceless. Why to your opinion Python has the 'not in' operator ?.
Code is written once, but read dozen of times so we should pay attention to how it reads, not really how long it takes to write. You won't be that happy everyone wrote their mail in this list like a mobile text message, if u c what I mean.

JM

 

[Jean-Michel Pichavant]

Although intuitively I would say the shorthand, however that is
depending on the context being me knowing at least the basics of 3d
spaces and having the pre-warning that you are going to mention
something with either coordinates or colours.

Take away this pre-information, as you would when first reading an
application, and all of the sudden the latter would be much clearer to
the fellow programmer.

I couldn't have said it better (I'll ignore the anti-camelCase lobby for
now )

In the middle of thousand lines of code, when you are reviewing or
debugging, the later is better TMO, the point is that x, y, z = is only
easy to read during the assignement. Consider this:

x, y, z = p.nextpoint()
[snip a dozen of code line]
....
....
....
....
....
....
....
....
y += 1 # hmmm ??


vs

xCoordinate, yCoordinate, zCoordinate = polygon.nextPointCoordinates()
[snip a dozen of code line]
....
....
....
....
....
....
....
....
yCoordinate += 1

JM

 

[Neil Cerutti]

In the middle of thousand lines of code, when you are reviewing
or debugging, the later is better TMO, the point is that x, y,
z = is only easy to read during the assignement. Consider this:

x, y, z = p.nextpoint()
[snip a dozen of code line]
...
...
...
...
...
...
...
...
y += 1 # hmmm ??

vs

xCoordinate, yCoordinate, zCoordinate = polygon.nextPointCoordinates()
[snip a dozen of code line]
...
...
...
...
...
...
...
...
yCoordinate += 1

_The Practice of Programming_ has this right. In general the
bigger the scope of a variable, the longer and more descriptive
should be its name. In a small scope, a big name is mostly noise.

 

[Steven D'Aprano]

In the middle of thousand lines of code,

If you have a function that is a thousand lines of code long, I don't
care what you name the variables, you won't be able to keep it straight
in your head.

This is one of the reasons why we break code up into functions -- so you
don't have to remember 1000 lines worth of variables names all at once.

when you are reviewing or
debugging, the later is better TMO, the point is that x, y, z = is only
easy to read during the assignement. Consider this:

x, y, z = p.nextpoint()
[snip a dozen of code line]
...
...
...
...
...
...
...
...
y += 1 # hmmm ??

A dozen lines isn't much. They will all fit on the screen at once.

Honestly, you guys are talking about variable names as if the average
coder was a moron barely more intelligent than a pigeon. Seriously, even
*goldfish* have better memory than that -- they can remember events for
many minutes at a time. That's the fatal flaw in your argument... if you
don't credit the average programmer with being able to remember that y is
an ordinate of a point after just twelve lines, what makes you think he
can remember that "yCoordinate" is the *second* item in the tuple, rather
than the first, or third, or twenty-first?

If coders were really as dim-witted as you seem to believe, you would
have to write:

firstItemOfPointCoordinates, secondItemOfPointCoordinates, \
thirdItemOfPointCoordinates = polygon. \
methodReturningNextPoint3ItemCoordinate()

Whew.


I find it ironic that after complaining about single character variable
names, you sign your post with your initials "JM" instead of "Jean-Michel
Pichavant".



By the way:

xCoordinate, yCoordinate, zCoordinate = polygon.nextPointCoordinates()

Coordinates are pairs or triples of *ordinates* (no "co"). You can't have
an "x coordinate" -- that would be like unpacking a single pair of shoes
into a "left-pair" and a "right-pair".

 

[Steven D'Aprano]

_The Practice of Programming_ has this right. In general the bigger the
scope of a variable, the longer and more descriptive should be its name.
In a small scope, a big name is mostly noise.

Thank you! The scope of the variable is an important factor.

+1

 

[Steven D'Aprano]

There is another important point: the time where code size matters is
over.

That's ridiculous. Which would you rather write?


import os
if os.path.exists("myfile"):
print open("myfile").read()


or this?

import the module called "os";
get the attribute named "exists" of the attribute named "path" of the
module called "os";
if it returns a true value when called with argument "myfile":
get the function called "open" and call it with argument "myfile";
get the attribute called "read" of it;
print the result to standard output;


Even by the standards of Apple's (much missed) Hypertalk, that's overly
verbose! Even Hypertalk compromised on perfect English grammar for
brevity and conciseness.

You
won't be that happy everyone wrote their mail in this list like a mobile
text message, if u c what I mean.

I never suggested that. What I am trying to get across is that long names
are not automatically better than short names, and even one letter names
can be as good or better than long names *when appropriate*.

 

[Jean-Michel Pichavant]

I never suggested that. What I am trying to get across is that long names
are not automatically better than short names, and even one letter names
can be as good or better than long names *when appropriate*.

You misunderstood my point, I'm not pro long names, I'm pro descriptive
names, It can be short if descriptive:

for o, c in cars:
park(o)
phone(c)

for owner, car in cars: # by just using meaningful names you give the
info to the reader that you expect cars to be a list of tuple (owner, car)
park(owner)
phone(car) # see how it is easier to spot bug


JM

 

[Mel]

Thank you! The scope of the variable is an important factor.

Wittgenstein remarked somewhere* "...it is the particular use of a word only
which gives the word its meaning...". For a variable, if you can see the
entire use at a glance, then any other cues to its meaning, like a long
variable name, are redundant.

Long variable names can lie; they share this ability with comments. The one
study** I've seen of newbie errors observed the #1 error being as assumption
that descriptive variable names could somehow replace computation, e.g. that
if you called a variable "total_sales", then accessing it would get you a
sales total, regardless of what you might or might not write as
computational statements.

Mel.

* "somewhere" hah! I covertly looked it up. It's in the _Blue and Brown
Books_.

** This I haven't looked up. It got some publicity a year or so ago. It
started when somebody gave a mid-term computer science test to a class who
had only just started the course. Then they studied the results to find out
what the students might have been thinking.

 

[Jean-Michel Pichavant]

Steven D'Aprano wrote:



Wittgenstein remarked somewhere* "...it is the particular use of a word only
which gives the word its meaning...". For a variable, if you can see the
entire use at a glance, then any other cues to its meaning, like a long
variable name, are redundant.

Long variable names can lie; they share this ability with comments. The one
study** I've seen of newbie errors observed the #1 error being as assumption
that descriptive variable names could somehow replace computation, e.g. that
if you called a variable "total_sales", then accessing it would get you a
sales total, regardless of what you might or might not write as
computational statements.

Mel.

So If I get you right, because comments can lie, we should stop using
comments ?
Computation never lies ? Well that's called a bug, and they are your
every day worries.

Meaningfull names helps spotting miscomputation.

total_sales = some_computation()
How are you supposed to verify that some_computation is filling its role
without even knowing what it is supposed to do ?

While I totally understand why some ppl prefer to use short names, I
really don't see the point in saying that because any information can be
wrong, we should stop giving any.

JM

 

[Neil Cerutti]

So If I get you right, because comments can lie, we should stop
using comments?

No, but use comment judiciously. Kernighan and Pike (_The
Practice of Programming_) recommend writing your code to require
as little comment as possible. They provide typical examples of
useful and of harmful comments.

While I totally understand why some ppl prefer to use short
names, I really don't see the point in saying that because any
information can be wrong, we should stop giving any.

Don't go that far. Applicable is Strunk's characteristic
admonition from _Elements of Style_: "Omit needless words! Omit
needless words! Omit needless words!" We should strive for a
balance between clarity and brevity. A useful comment, for
example one which provides references to documents on the
algorithm implemented in your module, should be included.
Beginner mistakes like, "define a class to model birds," and, "#
increment the total," are worse than empty space.

 

[Seebs]

Although intuitively I would say the shorthand, however that is
depending on the context being me knowing at least the basics of 3d
spaces and having the pre-warning that you are going to mention
something with either coordinates or colours.

Take away this pre-information, as you would when first reading an
application, and all of the sudden the latter would be much clearer to
the fellow programmer.

Would it really? Would it stay clearer to the new programmer for more
than two or three minutes?

I don't think it would. At worst, the new programmer has to look up
coordinates, once, and then we're back to the state where calling them
x, y, and z, or calling them r, g, and b, is MUCH easier on the new
guy.

-s

 

[Seebs]

In the middle of thousand lines of code, when you are reviewing or
debugging, the later is better TMO, the point is that x, y, z = is only
easy to read during the assignement.
Bull.

x, y, z = p.nextpoint()
[snip a dozen of code line]
...
...
...
...
...
...
...
...
y += 1 # hmmm ??

Uh, no.

That is not confusing at all. That is CLEAR AND TRANSPARENT.

yCoordinate += 1

In the real world, this will take substantially longer for the reader
to comprehend. You've just taken the important information (y), and
hidden it behind 10 times as much UNIMPORTANT information. You're
forcing them to read 11 characters, 10 of which are just tagging,
and made it much easier for them to miss that the "y" here should have
been an "x", because the word is 90% correct anyway...

-s

 

[Seebs]

Let me quote the paper I linked in the previous post:

list1 = []
for x in theList:
if x[0] == 4:
list1 += x;
return list1

compare it to:

flaggedCells = []
for cell in theBoard:
if cell[STATUS_VALUE] == FLAGGED:
flaggedCells += cell
return flaggedCells

The latter is better, but:

flagged = []
for cell in board:
if cell.flagged():
flagged += cell;

is probably even better. (Here's where I love Ruby's idiom of
"flagged?" as a method name.)

The "Cells" suffix on flagged is questionable; I'd omit it in context because
the programmer knows we're working on cells. The "the" prefix on "theBoard"
is actively harmful -- it communicates nothing and clutters. Adding symbolic
words to the cell[0] == 4 test is a great idea, but it's been done
questionably:
1. Did we just clutter the entire global namespace with "FLAGGED"
and "STATUS_VALUE"? If not, what namespace are they in, that
we're able to use them unqualified?
2. Why are we exposing that much of our interface in the first place?

-s

 

[Seebs]

It can be short if descriptive:

for o, c in cars:
park(o)
phone(c)

for owner, car in cars: # by just using meaningful names you give the
info to the reader that you expect cars to be a list of tuple (owner, car)
park(owner)
phone(car) # see how it is easier to spot bug

In this case, yes.

The one that brought this up, though, was "except FooError, e:", and in
that case, there is no need for any further description; the description
is provided by the "except", and "e" is a perfectly reasonable, idiomatic,
pronoun for the caught exception.

-s

 

[Arnaud Delobelle]

Coordinates are pairs or triples of *ordinates* (no "co"). You can't have
an "x coordinate" -- that would be like unpacking a single pair of shoes
into a "left-pair" and a "right-pair".

Wrong, the ordinate is specifically the second coordinate (the first one
being the abscissa). I don't think these words are in common use in the
english speaking world though (in France, "abscisse" and "ordonnée" are
terms taught at school). The terms x-coordinate and y-coordinate are
very commonly used.

 

[Steven D'Aprano]

Wrong, the ordinate is specifically the second coordinate (the first one
being the abscissa). I don't think these words are in common use in the
english speaking world though

I'm pretty sure they never used the term abscissa when I was at
university, and the word sounds very old fashioned to my ears... like
something Newton would have said. But I see that both Mathworld and
Wikipedia agree with you, as does my copy of Collins Dictionary of
Mathematics, so I stand corrected.

 

[Steven D'Aprano]

While I totally understand why some ppl prefer to use short names,

Oh the irony.

I
really don't see the point in saying that because any information can be
wrong, we should stop giving any.

It's only in your fevered imagination that people are saying that. Nobody
says that we should stop giving *any*.

Words gain their meaning from convention and common usage. There is
nothing about the word "car" that suggests a metal and plastic mechanical
transportation device that people sit in and travel across bitumen or
asphalt roads, it is only common usage that makes it so.

There's nothing about the word "sales_total" that means the sum of the
numeric sales figures for some given time period. It is only common usage
that makes it so.

Some words are shorter than others. In English, the noun "I" is a single
letter, but it has a known meaning. In French so does the word "y".
Spanish also has a word "y", but it's not the same word. A word doesn't
cease to have meaning just because it is short.

Common programming usage makes it that a variable called "i" usually
means a generic integer, especially if it represents an index. Common
usage makes it that a variable called "s" is a generic string. If you
flout these conventions, and write code like this:

def prepend(d, i):
"""Return string d with string i prepended to it."""
if not (isinstance(d, str) and isinstance(i, str)):
raise TypeError("expected two string arguments")
return i + d

then people will rightly laugh at you for misusing common names. And if
you pay no attention to these conventions, and write:

def prepend(string_to_be_prepended_to, string_to_prepend):
...

people will *also* laugh at you for being needlessly verbose. The
sensible middle-ground would be something like this:

def prepend(s, prefix):
"""Return string s with prefix prepended to it."""
if not (isinstance(s, str) and isinstance(prefix, str)):
raise TypeError("expected two string arguments")
return prefix + s

although I wouldn't mind if you used "string" instead of "s". Both would
be acceptable to me.

 

[Steven D'Aprano]

Long variable names can lie; they share this ability with comments. The
one study** I've seen of newbie errors observed the #1 error being as
assumption that descriptive variable names could somehow replace
computation, e.g. that if you called a variable "total_sales", then
accessing it would get you a sales total, regardless of what you might
or might not write as computational statements.

I've seen newbies do that, but I had never put two-and-two together and
realised *why* they do it.


That's a great observation -- thank you for sharing it.