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.

In reply to Re: The difficulties of commenting code by pmas
in thread 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.