Re: What makes a comment "obnoxious"?

[saberworks]

Yes, I find large groups of hash marks completely annoying. Your subs should be separated by meaningful comments that detail what the function does, what it expects as arguments, and what it returns. If you have a decent syntax-highlighting editor, your pod comments should be enough to provide a very easy-to-see separation between your subs. If I'm scanning through subroutines, I just search for the word "sub" and hit next, next, next, etc.

[adrianh]

Your subs should be separated by meaningful comments that detail what the function does, what it expects as arguments, and what it returns

Or (even better!)

• The function name should reveal what the function does. If it doesn't change it.
• The name of the vars you rip out of @_ should reveal what the function takes. If they don't change them.

• The name of the variable you a return() should reveal what is being returned. If it doesn't update it.

(guess who is thoroughly sick of lying comments in legacy code :-)