Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister

Re: I fear my code is unreadable

by jplindstrom (Monsignor)
on May 06, 2008 at 14:06 UTC ( #684950=note: print w/replies, xml ) Need Help??

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


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?

  • Is it a boolean?
  • Is it timeout in seconds?
  • Is it timeout in minutes?
  • Is it timeout in days?

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.


Log In?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://684950]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (1)
As of 2023-03-24 07:23 GMT
Find Nodes?
    Voting Booth?
    Which type of climate do you prefer to live in?

    Results (60 votes). Check out past polls.