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...

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.