Simple scalars may often have descriptive names, but I just wrote this:

my $standard={}; # the structure that contains all the standard info
                 # a hasref to
                 # title    => "standard title"
                 # dir      => standard directory (where the standard 
+page and graphics are)
                 # des      => designation            (802.11a-2000)
                 # norm_des => normalized designation (802_11_a_2000)
                 # def      => hasref { term => "html definition" }

[download]

I found this kind of comment to be immensely useful several month later when I need to fix a bug (rare ;--) or to add features to the code (often!).

And yes, the data represents a view of a standard, hence its name, but there are many infos that can be stored about a standard, it helps to know exactly which one this data structure is providing.

BTW, while I agree that this structure could be an object, I don't think that the specific program I am working on requires OO. And in any case it is nice to have all the docs about the variable right where I declare it.

In reply to Re: Re: Re: Perl Programming guidlines/rules by mirod
in thread Perl Programming guidelines/rules by hakkr

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.