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!!!!

In reply to The difficulties of commenting code by Henri Icarus

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.