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.

In reply to Re: Too much documentation? by chumley
in thread Too much documentation? by melguin

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.