Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number
 
PerlMonks  

comment on

( [id://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?"

Tony


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

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • 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.
Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others surveying the Monastery: (5)
As of 2024-03-29 07:46 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found