http://www.perlmonks.org?node_id=52592


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

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