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.