I heartily disagree Abigail's comment that people who document every sub are wrong. There is no such thing as too much documentation, no matter how redundant it may be.

Abigail's a pretty smart person, and I think the slip from "comment" to "document" was unintentional. Yes, you should always document your whole public API. Otherwise it's not really public, is it?

But don't waste my limited screen real estate on crap like this:

  #
  # Class->foo() - returns the value of foo for the object
  #
  sub foo { $_[0]->{foo} }

Another commenting pet peeve:

  # if $x is bigger than 10
  if ( $x > 10 ) {
      # set $x to $y modulus 50
      $x = $y % 50;
  }
  # otherwise, if $y is not equal to 50
  elsif ( $y != 50 ) {
      ...
  }

Argh! I hate that so incredibly much. Comments that simply tell me _what_ the code is doing are absolutely, utterly useless. Always assume that the next person does understand programming logic, assume that they understand Perl, etc.

Don't assume they know why something is the way it is, however. In the above code, I want to know why it's important to set $x to the $y modulus 50 only when $x is greater than 10.

There are a few exceptions to the "no walk-through comments" rule. Very complicated algorithms may deserve very careful step by step comments. This can help you as you code, in making sure that you're actually following the algorithm, and it helps future readers. And if you deliberately write less-than-clear code, for example as an optimization (after benchmarking and profiling, please), then it may be worthwhile to comment the what of the code.

But a good rule to follow is that if you think the what of the code is too hard to follow without comments, then you need to rewrite the code in a clearer manner.