Re^2: What makes a comment "obnoxious"?

[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 :-)