Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

Actually most of what you are putting them down for is actually good advice. I likewise use few comments, use descriptive variable names, comment each function, etc. If you are relying on understanding comments rather than figuring out the code, you will have serious problems when the two disagree.

This is only true when you fall into the common trap of believing that comments are about explaining what you're doing in the code.

Comments shouldn't be doing that. The code should be easy enough to follow that it's pretty clear what it's doing.

Comments should be explaining WHY you're doing what you're doing. That's the bit that's hardest for someone to reconstruct after the event:

"Yes, I can see that this loop is stepping through each item, building a hash of hashes of their info keyed by concatenating the title and the ID ... but WHY?"

Once you realise it's so they can easily sort by title at the end, but that keying the hash on title wasn't enough as not every product had a unique title, then this makes sense. A well written comment would have made this process a lot easier, however.

Comments are there mainly for the benefit of anyone who has to maintain your code later (including yourself!). They should explain all the bits where people will go "So, why exactly are they doing this like this?"


In reply to Re: Re (tilly) 1: What you want and perl advocacy gone way wrong by salvadors
in thread module info by ivory

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, 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, 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.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others perusing the Monastery: (6)
    As of 2020-02-29 13:31 GMT
    Find Nodes?
      Voting Booth?
      What numbers are you going to focus on primarily in 2020?

      Results (128 votes). Check out past polls.