in reply to Documenting Methods/Subs

At work we have a book of coding rules, which says to put a chunk of comments before each function, name of function, what it does, parameters etc. I find it helpful when using/maintaining code from other people (which sometimes hasn't been touched in years and the author isn't available any more..)

In code I write for myself (primarily), I usually do something like:

sub blahfasel { # This function does XYZ # Parameter: This, That ... }
One or two lines is usually enough, the actual code only has comments in parts where I feel they are necessary to explain what it's doing.

I keep meaning to learn POD and add that, but it won't be as a replacement for comments, just to provide an overview how to use the modules without having to look at the code.
C.