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.

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.