in reply to Re: Of variable {mice} and its name {man}.
in thread Of variable {mice} and its name {man}.
...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.
|
---|
Replies are listed 'Best First'. | |
---|---|
Re(3): Of variable {mice} and its name {man}.
by Dog and Pony (Priest) on Jun 03, 2002 at 07:28 UTC | |
by theorbtwo (Prior) on Jun 03, 2002 at 07:56 UTC | |
by Dog and Pony (Priest) on Jun 03, 2002 at 09:51 UTC | |
by theorbtwo (Prior) on Jun 03, 2002 at 21:44 UTC |