Well, I used to put something like the following at the top of my programs:
#D:/perl/bin/perl.exe -wT
# Last updated June 22, 2001
#
# Program: sys_admin.cgi
# Author: Curtis Poe
# Date Created: May 29, 2001
# Purpose: This program drives the various pages that are contained
# in the sysAdmin section of the blah-blah-blah site
#
# Inputs: All inputs will be from user-submitted form data with
# database info accessed through Blah::Database module
#
# Outputs: Returns HTML doc controlled by param('page')
#
# --------------- Maintenance log ------------------------
# Date:
# Programmer:
# Action:
# --------------------------------------------------------
use CGI;
use CGI::Carp qw/fatalsToBrowser/;
use strict;
use Template;
The fatalsToBrowser and -w switch are removed when the code is moved to production
(note that the
comments above are deliberately minimal). However, I have since decided to switch to
POD for all
comments. For example, all subs are commented with POD with sample usage:
sub some_sub {
=end
=head1 sub some_sub
=head2 my $foo = some_sub( $bar, \@baz );
=over 4
=item C<$foo>
C<$foo> will containt a ref to an hash with keys being department names and values
...
More stuff here
=back
=cut
The benefit of switching to POD for documentation should be obvious: when you're
finished, if
you've done everything properly, simply run your favorite POD converter and you have
good
documentation for most of you program. At the very least, maintenance programmers who
come behind
you will worship you :)
Cheers,
Curtis Poe
=====
Senior Programmer
Onsite! Technology (http://www.onsitetech.com/)
"Ovid" on http://www.perlmonks.org/
__________________________________________________
Do You Yahoo!?
Get personalized email addresses from Yahoo! Mail
http://personal.mail.yahoo.com/
