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 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.