=head2 insertRows($nameTable, $raRow)

Insert the data in $raRow (array ref with hash refs (key:
field name, value: field data) into $nameTable.

Return 1 on success, else 0. Die on fatal errors.

=cut
sub insertRows { my $self = shift;
    my ($nameTable, $raRow) = @_;
[download]

It describes the interface to the method. So you don't have to read the code to know how to use it. But you need to keep it in sync with the implementation, so the POD should be next to the method (Locality breeds Maintainability).

If you write the interface description before you start coding the method, chances are that you'll think one more time about edge cases, error conditions and stuff like that. Personally I find that a very useful way of organizing my thoughts before diving in.

Names of classes, variables, and methods should be meaningful and consistent. That way you don't need so many comments. Try to avoid abbreviations.

I find it useful to include the "domain specific data type" in the variable name to indicate what it contains, especially when using dynamically typed languages.

$timeout    vs $secondsTimeout
$table      vs $nameTable
$workspace  vs $dirWorkspace
[download]

When you do comment, note the why, not the what. Write down assumptions, thoughts and non-obvious design decisions.

Having said that, it is ok to say what a regexp does, because it's often not obvious. It's useful to provide a sample of what you're trying to match. Alway use /x to make it more readable.

If you look at CPAN, each module has a SYNOPSIS section with short examples. These are very powerful.

Apart from all other benefits with unit tests, they also provide great hands-on documentation, like a SYNOPSIS on steroids.

/J