In a talk on YAPC::Europe, Michael Schwern claimed that the breakdown was something like 40% code, 40% documentation and 20% comments in the code, but note that he's heavy on writing (code-)user documentation together with the code.

Personally, I tend to use very few comments, as I feel that my code should speak for itself - and any piece of code that I think could do with more comments is a good target for rewriting. Most of my comments only state what's happening (supposed to happen) as the programs goal, and not how it is achieved, except maybe for the design pattern used to implement the behaviour. But one reason why this works is, that I try to "speak" in the language I program in, that is, I try to only use idioms of that language to accomplish what I need. If I were to implement less known algorithms or heuristics, they would need plenty of documentation.

The only disadvantage to having a huge amount of comments is that you may be causing confusion. Try to be concise and clear, but use as many words as you must to get your point across.

Bad comments are ones that are completely obvious simply from looking at the code. For example,

# Print the contents of the string variable $foo
print $foo;
[download]

For me, I put the complexities in my data, document the data and call it a day. Sometimes it's necessary to provide a road map for large programs, but any more than a couple of lines of comments for each function means that I'm doing something wrong.

The one exception to this being places in the code that I know are going to have to be changed: a future programmer will have to meddle in it, and a config file would be overkill. These I block out to be obvious, and then document each and every single thing carefully.

 
___crazyinsomniac_______________________________________
Disclaimer: Don't blame. It came from inside the void
perl -e "$q=$_;map({chr unpack qq;H*;,$_}split(q;;,q*H*));print;$q/$q;"

40 percent is about right, but there is quite a large spread, see Some simple metrics.

This is something that has changed for me several times over the years. When I first started, with BASIC, I used "A", "B", "C", etc. for variable names and didn't document anything. Fortunately I had nun for a CS teacher who beat that habit out of me. (Sorry... pun unintentional!)

Lately I have tried to use descriptive names for variables and routines, short comments where they're needed, and larger blocks of "pretty" comments to break up major sections. For example I am working on a project at home that uses both DBI and Tk. I am putting Tk-related functions in one section, and DBI functions in another, separated with something like this:

############################################################
#
# This is the "meat" of the program where all the
# database stuff is hidden. Everything up to here
# is the Tk interface.
#
############################################################
[download]

I also try to choose subroutine names and variable names so they make sense. For example:

sub get_subject_list
{
    my @list;
    my $topic;

    my $dbh = DBI->connect("DBI:CSV:");
    my $sth = $dbh->prepare("SELECT subject FROM subjects");
    $sth->execute();

    while( $topic = $sth->fetchrow_array )
    {
        push(@list,$topic);
    }    

    return @list;

    $dbh->disconnect();

}
[download]

It should be fairly obvious what's going on here. At least, if I read this code in a few months I will know what's going on.

So far this program prints out to 5 pages, with about 55 lines of comments. That's close to the 5:1 code to comments ratio that melguin mentions. I may add a long section at the top which documents all the naming convections and subroutines I used, but that comes later. I also find it easier to put the POD at the end of the file after all the Perl code. I have tried interspersing POD in the code but it didn't work well for me, partly because I try to use POD and comments for separate purposes.

Chumley

Imagine a really clever .sig here.

i think that ultimately the nature of the organizational environment might be the prime determinant. if your work would ultimately be maintained by perl cognisceti, your requirements are likely going to be different than if it were to be handed to a vb programmer.

$i++   # incrament i

This is one of the forces that needs to be balanced in order to find the right mix of comments to code.

The eXtreme Programming folks take an extreme view on comments. They hold that comments are one of theCode Smells that are clues that your code has problems. If you need to write lots of comments, it's an indication that your code isn't clear enough, and that you should put effort into cleaning up the code so that it describes itself.

(This is a point on which reasonable people can differ.)

In there I lay out in quite a bit of detail my opinions on ways in which commenting can be negative, what needs comments, what does not, and how to comment. As you will see reading that, the question isn't really the density of comments. It is instead what do you comment, why do you comment, how do you comment, and in what ways do you make your code descriptive?

When I started my current job, I'd put block comments everywhere in my code, saying what assumptions I was making and what was going on. Now, I've been moving away from gratuitous commenting: it's better, I think, to make the code speak for itself than it is to write bad code and tell the reader what it's supposed to do. (When that code changes, the comments usually get left out of date.)

My strategy now is this: write code to be as obvious as possible, and comment what's left over. Telling the user that &validate_foo validates a foo's value isn't especially useful, but saying that it expects a single reference to a foo is, for instance.

Update: Now that I think about it, &validate_foo is a horrible name for a subroutine, since it gives no clue as to what it returns. &is_valid_foo makes much more sense. (Although if having an invalid foo running loose in your code is a fatal error, then &validate_foo might just die or croak if the foo it was passed is invalid; if so, it should damn well be documented.)

Over the years I've noticed that I've become a little bit schizophrenic about documentation. For example, the first thing I do when evaluating someone elses code is to create a copy without comments at all. I'd rather see what the code is doing without being distracted by what the author thought it was doing! On the otherhand, I prefer to code using some form of Literate Programming (see Knuth) whenever I can. I think that this kind of contradiction demonstrates that this is a hard topic!

Some sort of version is also important, but often this comes from an external revision control system.

The most important code comments explain the known defects, limitations and the problems in your code.

Comments tend to say what you hoped your program would do. Just when you need the comment the most, it lies!

When I am tempted to write a comment to explain something, I try to reformulate the comment into an error message. I use something like the or die idiom used when opening files. This gives me nice a spot to put my description of what is going on. It is also easier to maintain. If the this doesn't seem natural, I put in a diagnostic print statement with a trailing if $verbose.

something_tricky() or die "Failed to execute the trick";
print "So far I have $my_intermediate_result" if ($verbose > 0);
[download]

It should work perfectly the first time! - toma