I agree - descriptive names are important, and comments far aways from actual code are seldom up-to-date: the farther away, the less likely to be updated.

Still is useful to describe usage of subroutine near sub definition and maybe relationship between parameters - common idea.

I *almost always* add one-line comments where variable is defined, something like:

sub foo {
    my $detailed_variable_name = shift;   # always some comments!!
    my $another_variable_name = shift;    # always some comments!! 
    my $return_value_ref = {};            # hash of values to return
   ...
    return $return_value_ref;
}
[download]

Lead programmer in company where I 'grow up' was very strict. He believed that programmer's freedom should not be wasted on inovative ways to invent new naming convention for each program. We used excellent editor (MultiEdit), what allowed with one click to grep all lines matching variable name under cursor (also the line where it was commented). It was good incentive to make one-line comment in the same line as my $varname = shift;

Also, I get used to write one-line comments in the same line for each procedure call (program names were in DOS, 8+3 characters, not too helpful for descriptive names. Such comments, once written, are easy to copy-paste.

pmas

To make errors is human. But to make million errors per second, you need a computer.