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.

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.