Good commenting is a purely subjective concept -- good for who?

Like any form of documentation, without knowing who the intended audience is, it's impossible to say what makes good comments for them. For instance, there's detailed commenting (POD or other more detailed comments, which are good for long-term maintainers or folks who may make use of your work in other projects, but placing it all inline can possibly make it more difficult to follow the flow of the code.

I'd propose that well written code can be self-commenting. If you select good variable, package, and subroutine names, that clearly describe their purpose in an unambigous manner, you can signficantly cut down on the amount of comments necessary.

Take, for example, the same two equivalent functions:

# Set a default value if null
# Input:
#    Test Value
#    Default Value
# Output:
#    Sanitized Value
sub nvl {
  return $_[defined($_[0])?0:1];
}

sub sanitize_undefined {
  my $test_value    = shift;
  my $default_value = shift;

  return $test_value if defined($test_value);
  return $default_value;
}
[download]

That's not to say that comments never help -- I add comments all the time, but I'd rather make the code clear on its own, rather than add comments so the code can be understood. I see no point in obfuscation for the sake of obsfucation. (It might be obscure, because it's odd logic, or you're doing something strange to deal with a specific problem condition, or even for the sake of tuning, but just trying to keep someone from understanding your code results in you not understanding your own code a few months down the road).

Update: added readmore tags