In his good post yesterday, Ovid asked about rewriting a large applications and one answer that came up over and over again was "Comment the inputs and outputs of each subroutine." By this I suppose folks meant that you should put one of those nice blocks at the begining of the code with lots of little descriptive text about parameters and return values, etc..

Now I don't know about you all, but I've tried to do this and, but invariably I end up needing to add another parameter, or change the result to be a list (or a reference) so that I can pass back multiple results, and then, (call me lazy :-) I forget to update my little comment block at the begining of subroutine. So later when I go back (or heaven forbid someone else does) to look at this subroutine and I read the comments, and I look at the code, and I'm worse off than if I hadn't commented it because things don't match.

So, lately I've just been sticking to things like:

# foo: reasonably general description of what foo does
sub foo {
    my $detailed_parameter_variable_name = shift;
    my $another_detailed_parameter_variable_name = shift;
    my $return_value_ref = {}; #hash of values to return
   ...
    return $return_value_ref;
}
[download]

So the wisdom I'm looking for is what others have found to be the most effective use of commenting time and coding style to maximize "self-documenting" of the code.

-I went outside... and then I came back in!!!!