Perl Adapter Project

These coding standards are meant to be a guide, something to shoot for, in our code.

As all of us programmers know, we like to use our own style, and our favorite editor. So what we would suggest is if you are extremely resistant to changing the way you like to type your code, you may want to get an editor like SlickEdit which can emulate vi or emacs and some other popular editors. Then set SlickEdit up to "beautify" your source after you've written your code so that it conforms to the standard.

The other thing that we would like to do is use pod2html. There is an example in the file header. Be careful to use it exactly as is because any additions or deletions of whitespace/newlines will confuse the pod2html program.

File names

File and Subroutine Headers

# ------------------------------------------------------------------------ #
# Copyright (c) 2000 Open3.org
# All Rights Reserved.
# 
# This software is licensed under the Open3.org Public License (OPL)
# By using, modifying or distributing this software in source code or binary
# format, you agree with the terms of the Open3.org Public License (OPL).
# 
# For more information, see:
# 
#      https://open3.org/licenses/OPL.html
# 
# OPEN3.ORG MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
# SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT
# LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE, OR NON-INFRINGEMENT. OPEN3.ORG SHALL
# NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING,
# MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
# 
# CopyrightVersion 1.00

=pod

=begin html
 

 File name:
 

 

     discount.pl
 
 

 File Description:
 

 

     This file is called from the output HTML of discount.cgi when the intranet
user wants to edit a discount.  This file is also called when the user saves 
the edited form.
 
 

 Modifications:
 

 

     
08.10.2000 - DLS - Original code completed.
     
09.10.2000 - SAF - Put in lots of comments.
 
 

 Author:
 

 

    Sarah A. Farrell
 
 

 Version:
 

 

    Revision: 1.2 Date: 09.10.2000
 
 

 See also:
 

 

 

=end html

=cut
# ------------------------------------------------------------------------ #   
use strict;
use CGI;
.....  
  
    

Here is an example of a subroutine header that you want to have converted into a Perl HTML document later on:

   
# ------------------------------------------------------------------------ #
=pod

=begin html
sub parse_data()


    description:

    

        

        This procedure is the meat of the whole 
program.  Determines how the CGI was called, then displays the form 
for an edit or form for a new entry, or if we're doing an update (calls
update()).
    
    

    params:

    

        none
    


=end html

=cut

# ------------------------------------------------------------------------ #

sub parse_data {
    my ($parent_data, $disc_code_id, $itemhash, $children_count, 
$listing_text);
    .....
}
....

    

Naming Conventions:

• FileNames.pl - No spaces. No underscores. Uppercase change for each word. This applies to package names as well (unlike Sun's Java Convention).
  
• subRoutineName - No spaces. No underscores. Lowercase first word, uppercase additional words.
• FILE_LEVEL_CONSTANT - Global variables that don't change (constants). All caps with underscores.
• variable - Lowercase, try for one descriptive word, or form it like "subRoutineName".
  You may use hungarian variable notation if you would like to. I don't.
  Use "my" liberally with variables inside subroutines.
  Don't overuse global variables.
  The more descriptive the name, the better.
  

Style Conventions:

• Indent, 4 spaces.
• Line up curly braces on separate lines.
  i.e.,
  

  
  for (my $i; $i<3; $i++)
  {
      if ($bogosUPC[$i])
      {
          my $item = $i + 1;
          ....
      }
      elsif (....)
      {
          ....
      }
      else
      {
          ....
      }   
  }
          

  Or alternatively a hybrid format:
  

  
  for (my $i; $i<3; $i++)
  {
      if ($bogosUPC[$i])
      {
          my $item = $i + 1;
          ....
      } elsif (....) {
          ....
      } else {
          ....
      }
  }
          

• Use whitespace when it makes things more readable.
• When in doubt, take up more lines to make it more readable.
• Comment your blocks when you feel the need to say why you coded something that way.
• Pre-qualify subroutines with "&" just to flag it as such.
• Put in the whole package name for clarity:
  i.e.,
  &Prescription::Intranet::AuditLogin("dailySpecials");
  
• Use a subroutine to separate one logical action that you might reuse. It is up to you to decide how much passing around of variables you would like to do and how much to make global. (NOTE: this will change if we decide to go with an Object Oriented Perl standard.)
• Put a subroutine in a package (Perl module) as soon as you find yourself using it in two or more files.