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.


In reply to Re: Re: Of variable {mice} and its name {man}. by graff
in thread Of variable {mice} and its name {man}. by vladb

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.