http://qs1969.pair.com?node_id=684950


in reply to I fear my code is unreadable

When people talk about self documenting code, this is what they mean: compare

$something + 2; #2 is the padding

with

my $padding = 2; ... $something + $padding;

Naming things right is one of the most important things in programming, and very often overlooked.

I can't tell from the context whether $padding is the best name for what it does. For example, maybe it's utterly obvious which unit padding is in (columns?), maybe it's better named if you include the unit ($cm_padding).

This is very, very often missing from variables containing some kind of time. As an example, what does $timeout mean?

The name could tell you all that ($is_timeout / $seconds_timeout etc).

The same thinking goes for naming configuration variable names. Actually it's even more important in config files because there is usually no context there whatsoever. In the source, at least you've got the surrounding code to get clues from.

This actually leads to another principle: the bigger the scope of a variable, the more important it is to get the name right, and the more explicit the name should be.

That means it's almost okay to name a for loop index $i, because that's both an expected convention and a very small scope.

Naming a global variable $i would be insane. The name needs to work in any context and it needs to stand on its own and carry meaning in all those contexts. In this case, $i doesn't mean anything.

/J