The "why not what" model of commenting is a really good idea, both because it is more useful, and because it prevents the "code and comments don't match" issue. If someone is changing a section of code so fundamentally that what it is trying to do is no longer the same, then they had better damn well add their own new comments anyway. For the most part, changes to existing code will be because it didn't work quite right or they wanted to add a little functionality, in which case the philosophy behind the section will remain the same, and the comments will remain valid.

But what I would really like to do is take a moment to shoot down the "don't comment too much" argument. Where did this come from? Can anyone seriously say that they've ever been reading some code and said to themselves, "Damnit, there are just too many comments in this code!" I didn't think so.

There is simply no such thing as too many comments, only poorly placed or badly formatted comments. Even if you comment every single line, it is only a problem if you do so in an obtrusive and annoying manner.

For example, consider the frequently used "box comment" style:

###########################################################
#
#   Here are some comments on the following code.
#   It does stuff.
#   Its cool.
#
###########################################################
[download]

This is a perfectly good style of comment, and should be used to mark off the beginning of every file, function, and major code section.

However, if you use this style of comment in the second loop of a triple nested while loop, it just breaks everything up. That is annoying and to be avoided. That doesn't mean that the section shouldn't be commented, merely that you need to employ a different style, like this one:

#
#   This is a less intrusive way of setting off a long
#   block of comments inside the middle of a function or
#   code block.  I also usually include a blank line at
#   the end for spacing.
#
[download]

Also popular are the "end of line" comments. The problem with these is that they can clutter things up just like people complain. The key is to use short comments and keep a uniform spacing. For example:

use strict; #always
my $this_is_ a_variable_name #does this comment stand out?
my $x; #how about this one?
my $what_is_going_on #where will the next comment be?
[download]

Those are ugly, confusing comments that blur in with the code visually, and thus make the code harder to read. Try this instead:

use strict;                  # always
my $this_is_a_variable_name; # does this comment stand out?
my $x;                       # how about this one?
my $what_is_going_on;        # where will the next comment be?
[download]

Now, the comments stand out well, and the code can be read easily. If someone wants to read the code, they stay on the left. If someone wants to read comments, they stay on the right.

However, avoid stupid comments such as:

$x++;  # increment $x
[download]

That's just commenting because you don't know what to do with yourself. Instead, comment it intelligently with:

$x++;  # keep track of how many users have logged in
[download]

The moral of the story is: always comment, but comment clearly, neatly, and intelligently. People who warn you to beware of "over-commenting" are arguing a non-issue. Of all of the comment-related problems that have arisen in the history of programming, "this code has too many comments" surely accounts for less than 0.1% of them. If you're worried about cluttered source, simply take the time to format your comments, separate with whitespace and indent liberally, and remember these words of wisdom from a programmer whose name eludes me:

With regards to commenting, I have this to say. Write all of your code so clearly, and with variable names so explicit, that it can be easily understood without comments. Then go back and comment it anyway.

Some people drink from the fountain of knowledge, others just gargle.

---

---

• 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.