Re: Of variable {mice} and its name {man}.

When I read this, I remembered something I think is from Fowler's Refactoring (I don't own the book, so I can't look it up):

One of the advices for what and when to refactor was that any time you feel the need to comment a block of code, to explain what it does, it was time to extract that piece of code into a subroutine and give it a good name. That way it would be obvious what happened at that place by reading the name of the sub, and the need for the comment disappear.

That also would apply here - as soon - or as long - as you (would) need a comment to explain what a variable is for, you should rename it to describe what it holds. This is essentially what you say above, of course - just thought it would be a (perhaps) good "rule of thumb" to keep in mind.

This still means that using for instance $i as an iterator variable in a for loop probably doesn't need any comment, and thus it doesn't need to be renamed either.

As many others have said, apart from one-liners and the like, I do try to name my variables in a readable fashion - matter of factly, my variable names are often quite verbose even in test scripts, because the extra typing does save time and pain even during the short time the test script lives. Otherwise I tend to resort to $_ and friends for Q&D coding. :) Noticable execptions include for instance my habit to name the CGI object $q, but that is kind of a convention, so I don't feel too bad about it. I do name the different Parser objects (like HTML::TokeParser) $parser etc, instead of simply $p.

---

You have moved into a dark place.
It is pitch black. You are likely to be eaten by a grue.

[graff]

I am fully in agreement with jeffa's and Foxtrot's handy rule of thumb, that the importance of a variable's name (hence its informative detail), should relate directly to its scope in the code, and its exposure to programmers other than the code author. With that in mind, I would warn against what seems to be a logical inference suggested by these statements:

...it would be obvious what happened at that place by reading the name of the sub, and the need for the comment disappear.
That also would apply here - as soon - or as long - as you (would) need a comment to explain what a variable is for, you should rename it to describe what it holds.

One should not interpret this to mean that a detailed variable name is sufficient to document the role of an important variable -- especially when the important variables tend to be heavy data structures (HoH, AoH, etc).

When an important variable is declared, of course its name should be meaningful, but there should also be some commentary to explain things that the name alone cannot convey: how it's structured, how it gets values assigned to it (is it filled from input? computed?), and/or what its values are used for.

For that matter, given the choice of "long variable name" vs. "short name with a descriptive comment on the initial declaration", I'll go for the latter; effective laziness in programming means, in this instance, doing something once (documenting a variable's role) and doing it well that one time, rather than doing it repeatedly (encapsulating "documentation" in the variable's name), but not doing it properly at any point.

[Dog and Pony]

I almost have to assume that you misinterpret this on purpose, possibly to point out that I wasn't very exact in my post. In any case:

You are confusing "how comments" and "what comments". In the example taken from Refactoring, you don't seriously believe that the name of the new sub should describe how the code works? No, it describe what it does, and what it is for. That should be pretty obvious.

Then for most code, especially in small blocks with good names, it should be quite clear what is happening from just reading the code - some people even advocate that if the code is well-written, it should not need any comments whatsoever. That I can't really agree on, there are always hairy parts that needs extra explaining. And as someone once said: "Good code has lots of comments, bad code needs lots of comments." - meaning that you should always comment your code, no matter which of them you write... especially since who are you to tell? :)

You think that it is somehow mutually exclusive with comments and verbose names. Why? Where did I say that you can't explain your data structure because you have a good name? The name is there so you can see what data is being worked on in the code, not so you can see how. That either is easy enough to read from the surrounding code, or is documented somewhere where it is easy to find.

Again, how contra what.

Documenting the variables name once like thus:

# Holds all employees names
my @em;

instead of naming it something like:

my @employee_name;

is your choice then? Well, it is not mine. If I have a semisized piece of code, then I don't want to have to go to the top of the program (potentially) to find out what each variable holds, each time I encounter them. If I know what data is in it, from the name, then I can work on. If I don't know the data structure, and it isn't possible to (easily) deduce from the surrounding code, then I'll go look for some docs on the structure. What or how.

Perl programmers often pride themselves on "Laziness", since it is one of the programmer's virtues according to Larry Wall. Well, there is false laziness too. Trying to "save time" by typing a few less keys is definetely false laziness - at least if you are trying to hold that as a virtue. As the XP and refactoring people say about writing tests - you have the extra time for it, because you didn't really code all, or even most of the time that you sat at your computer anyways. As with tests, you can save a lot of maintenance and bug fixing by being clear about what happens. Even if apt naming isn't gonna do a big difference on its own, together the small things count. Beware of false laziness.

---

You have moved into a dark place.
It is pitch black. You are likely to be eaten by a grue.

[theorbtwo]

Refactor your names, too. Is it significant to the code that these are employees? If not, @names is a perfect name. @en is overshorting. @employee_names is overspecifing.

If it is significant to the code that these are empoyees you're naming, why? Does this mean that if you were dealing with customer names, the code would be completly inapproprate? Why?

Every character really does count. (Check how many different ways I've mistyped employee in this post, and how many you noticed being wrong.)

---

We are using here a powerful strategy of synthesis: wishful thinking. -- The Wizard Book