Problems? Is your data what you think it is? | |
PerlMonks |
Re: Re: Of variable {mice} and its name {man}.by graff (Chancellor) |
on Jun 03, 2002 at 03:09 UTC ( [id://171115]=note: print w/replies, xml ) | Need Help?? |
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.
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 Section
Meditations
|
|