me too... document the hell out of methods; try to make the code within the method self-documenting by judicious use of descriptive variable names, and comment whatever isn't obvious.

guess my complaint about POD and Perl is the lack of a more precise documentation markup/syntax. With POD, one can only really =head and =item and such, but what i think we really need, especially in a weakly typed language like Perl is something more like:

=public =object =method get_name

=usage  <string> $name = $this->get_name();

=args  <none>

=returns $name

The current user's name.

=description

Basic accessor method to get user's name.
 
=cut
sub get_name {
    ...
}

...and then someone (me!) could write a parser which would be able to create beautiful, standardised, perl doco for every module under the sun, rather than the diverse, often terse, sometimes overly verbose, and occasionally obscure doco that exists for modules on CPAN...

just a wish... (thoughts turn longingly to function prototypes in Perl 6...)

d_i_r_t_y