Network Services Programming Style Guide - Tool Template for NS Scripts and Tools With Comments

This document presents the various sections of a typical script along with explanations for each section.
#! /usr/bin/perl -w


#============================================================
#    S C R I P T  F I L E N A M E .  P L
#
#    $Id$  <- RCS will automatically add version and author info here
#
#    A short, one or two line description of what this script does.
#    Written by A. User 
#============================================================


#============================================================
#   U S E  /  R E Q U I R E
#   Perl modules and perl libraries that are needed by this script go here.
#   'use strict' MUST be included here.
#============================================================
use strict;

#============================================================
#    P R O T O T Y P E S
#    Subroutine and function prototypes go here, if there are any.   
#============================================================
sub mySubroutine($;$);  # '$' means a required parameter, ';$' means an optional parameter
sub myFunction($;$);


#============================================================
#    C O N F I G
#    These are variables that might change if the script moves.  
#    Constants also go here.
#============================================================
my $rcs = '/usr/bin/rcs'
my $email suffix = '@wisc.edu';
my $ARG1 = 'foo';
my $MONTHS_IN_YEAR = 12;


#============================================================
#    G L O B A L S
#    These is where global variables go.  Basically these variables should only be used
#    in the main() method.  All other variables should be passed to subroutines as
#    parameters except in rare cases.
#============================================================
my $main_result = undef;
my $arg3 = 'foo';
my $arg4 = 'bar';


#============================================================
#    M A I N 
#    The main method of the script starts here.
#============================================================

#===== A comment describing what we're doing in the next two steps
mySubroutine($ARG1, $MONTHS_IN_YEAR);
$main_result = myFunction($arg3, $arg4);

#===== Print our results
print "$main_result\n";

exit;  # the main method of the script ends here and the program exits here


###################### BEGIN SUBROUTINES #########################


#============================================================
#    M Y  S U B R O U T I N E 
#    Arg1: A description of the required argument to this subroutine.
#    Arg2: A description of the optional argument to this subroutine.
#    A short explanation of this subroutine.
#============================================================
sub mySubroutine($;$)
{
  my $arg1 = shift or
    die "Must supply arg1 to myFunction()!\n";  # Required arg, die if not present
  my $arg2 = shift;                                             # optional arg, don't die if not present

  #  Do some stuff

  return;

} # end of mySubroutine()

#============================================================
#    M Y  F U N C T I O N
#    Arg1: A description of the required argument to this subroutine.
#    Arg2: A description of the optional argument to this subroutine.
#    Returns: A description of what this function returns.
#    A short explanation of this function.
#============================================================
sub myFunction($;$)
{
  my $arg1 = shift or
    die "Must supply arg1 to myFunction()!\n";  # Required arg, die if not present
  my $arg2 = shift;                                                # optional arg, don't die if not present
  my $result = '';

  # Do some stuff and store the results in the variable $result

  return($result);

} # end of myFunction()