I've seen it here, but one bit of advice was don't comment your code, comment your meaning. In order to do this, you need to write code that can be understood what it does without comments. If you do something particularly convulted, this may not be the case that then that part in particular comment the code. But if you code can be understood on what it's doing, your meaning is why you are doing it.

A comment along the lines of: # The following replaces all occurances in @awb_lines of the XX_C1 placeholder with $company That tells me what the code does. As a coder, I should be able to figure that out. (Unless, of course, Erudil or BooK wanted to hide that from me, or merlyn was playing with map, but I digress.) A much more useful comment from my viewpoint would be: 

# Update the email version of the airwaybill (@awb_lines) with
# the correct sub-company name ($company) that is handling the
# shipment

[download]
Not much different, but now if someone else is maintaning your code, and there is a much better symptom to solution connection. Someone can take outside-the-program infomation ("Hey, it always doesn't have the right shipper on the AWB") and quickly connect this to the program. Without havign to hunt through logic to understant that @awb_lines is what's needed. (BTW, I needed a quick example, if I really was doing this, I would probably do this differently.)

Even in this example, I was guilty of not using variable names that were descriptive enough. If your code documents what it does, and the comments document why it does it, and you have sufficient usage via POD, you're sitting pretty. (And doing better then me.)

=Blue
...you might be eaten by a grue...

In reply to Re: Another commenting question, by Blue
in thread Another commenting question, by scottstef

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.