Code should be self-documenting in the way that it should be obvious what you are doing.

If it's not (e.g. a hairy regexp, or an effective but maybe-too-advanced-for-your-colleagues Perl idiom), a comment is useful. Or, if the code is too opaque, a comment can provide guide to what happens.

But there are other cases.

Why you do things are sometimes not obvious. Or it may be obvious to you, but it won't be to the maintenance programmer (that's you, in six months). But why is different from what. Code the what and comment the why.

Some things are by definition not obvious. The interface (what you have in your example) should be explicitly documented for two reasons; it defines what the method/function actually does, and; before using a method you shouldn't have to spend time to understand how the code works, only what it does. And with a weakly typed language like Perl, it may not even be possible to deduce what kind of object to pass a method just by reading the code.

The following example is from a program for replicating subsets of a Wiki to other Wikis.

=head2 replicateSelection()

Replicate the selected pages in the local oWireLocal to this
remote Wiki, if appropriate (i.e. this remote Wiki owns it).

Return 1 on success, else 0.

=cut
sub replicateSelection { my $self = shift;

    logDebug("Replicating to (" . $self->urlWikiRemote() . ")");

    for my $name (@{$self->oWireLocal()->raNameSelection()}) {
        if($self->rhNameOwner()->{$name}) {    #Do we own this page?
            $self->replicatePage($name) or return( logError("Could not
+ replicate page ($name)") );
        }
    }

    return(1);
}
[download]

The POD defines what the method does, and what it returns. If it was possible for it to die, that would be mentioned. The comment explains in user-level terms what the hash ref indicates.

From the same program:

=head2 raExtractNamePageRecent([$html])

Return array ref with names of recently changed nodes/pages. 
Order: unique, most recent first.

If $html isn't passed, get the input from the Wiki.

Return undef on errors.

=cut
sub raExtractNamePageRecent { my $self = shift;
    my ($html) = @_;
    defined($html) or $html = get( $self->urlFromName("RecentChanges")
+ ) or return(undef);

    my @aName = ($html =~ m|&nbsp;</td><td><a href="[^"]+">([^<]+)</a>
+</td>|gs);

    #Already unique, because they are unique on the web page
        
    return(\@aName);
}
[download]

The POD says what the method expects as input, what it does, and what it returns. The comment explains why duplicate names are ignored--there are none.

I find it very useful to write the interface before coding the method. Yes, I know pretty well what I intend to accomplish when I start out, but writing the POD first gives me ten more seconds thinking about the problem, including the important things like what goes in and out, what boundary conditions there are, and how to handle errors. I wish to think that this improves the quality of the code.

Documenting the interface using POD instead of Perl comments makes is easy to extract the class definition programmatically, e.g. using (warning, shameless plug ahead) Perl Oasis:
http://www.bahnhof.se/~johanl/perl/Oasis/pic/screenshots/image017.gif

/J