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

    $something + 2; #2 is the padding

[download]

with 

    my $padding = 2;

    ...

    $something + $padding;

[download]

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

In reply to Re: I fear my code is unreadable by jplindstrom
in thread I fear my code is unreadable by Boldra

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, details, 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, summary, 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.