It can get to the extreme, very easily. Consider a simple sub to commify a number, called commify_number. There's no need for this to have a description of what it does - it's obvious. Large blocks of comments (or comments documenting most of the lines of code within the sub) for something like this are going to obscure what should be a relatively simple thing.

My thoughts: if code is getting lost in a sea of comments, there's too many comments. Redundancy is largely irrelevant if the comments themselves are stopping you seeing what's going on.

While I agree that a lack of docs is bad, it's very important to get some sort of balance between code usability (in a maintenence sense) and understanding, at least in my mind.

-- Foxcub

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

  # 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 ) {
      ...
  }

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.

There is no such thing as too much documentation, no matter how redundant it may be.

Whew! Obviously you haven't seen the code I have.

use warnings; # turn warnings on
use CGI;      # use Stein's CGI.pm for parsing params

my $q = new CGI; # create the CGI.pm instance

# get the customer's name (in the name parameter)
# place in in variable $customer_name
my $customer_name = $q->param("name")

# if the customer's name is "Bobby"
# print "Hi Bobby"
if ($customer_name eq "Bobby") {
    print "Hi Bobby\n";
} else { # if not, print "You're not Bobby"
    print "You're not Bobby\n";
}
[download]

Get the point? This completely distracts from the code and takes way more time on the part of the programmer.

As for subs, I say one comment directly above them. Anymore and the sub is too long and should be broken into multiple subs.

There is no such thing as too much documentation, no matter how redundant it may be. Lack of documentation is almost always wrong (programmers should not resort to sourcediving to learn function names).

Lack of needed documentation is always wrong - however over documentation, in my experience, can cause problems. For example:

• Excessive documentation/comments can be an excuse for poor code. Rather than spend the effort to produce comprehensible code certain developers will write a long and complicated piece of text to justify their technique. It sounds weird I know, but I've come across it enough times for it to become a personal anti-pattern I keep an eye out for.
• People change code and do not change the comments/documentation. The more redundent documentation there is the worse this problem gets.
• Documenting to early. If you're in an environment where the code is changing rapidly, methods and classes are being refactored and moved around on a daily basis, etc. then time spent documenting and commenting is wasted time.

Personally, I tend to go for development environment with common code ownership and require unit tests for everything. I find this removes most of the need for comments and heavy API documentation during development.

If the team discovers a need for documentation during development then we do it. If the team is not in-house then we will also have appropriate levels of design & implementation documentation as a deliverable (and we'll do it properly too :-)

This has worked well for me with smallish projects (about a dozen coders max).

All methods must be documented

And so do I. Whilst I take your point that it's generally a good idea to document the methods that make up your public API, those methods will not be the same as the full set of methods to which an object responds.

Anyone who works with your code needs to see documentation covering how you expect the code to be used (though I'm as guilty as the next man of failing to do this on one of the major projects I'm working on, partly because the API is still in flux). Anyone who works on your code should be using the source like God intended. And if you're not competent to write clear code then what on earth makes you think you're competent to write clear comments in a far more ambiguous language?

There is no such thing as too much documentation, no matter how redundant it may be.

Yes there is. I'm working on replacing some programs right now that stop every 5 lines or so with 20 lines of comments. Just document the subs if it's not obvious from their names, then document anything you do that's clever but obscure. Anything more gets in the way of following the code, which is The Ultimate Documentation.