NAME

Perl Programming Style Guide

AUTHOR

Brent S.A. Cowgill, B.A. Sc.

DESCRIPTION

Adopting a consistent style of programming can enhance comprehensibility of programs, reduce bugs and ease maintenance. In addition, it reduces the number of decisions to make when writing a particular block of code.

This guide is a statement of my personal programming style. For the most part, I follow these guidelines whenever I develop code. Many of the concepts in this style guide were borrowed from the CPAN perl style guide.

This was done for efficiency, as I discovered that many of the style guidelines I follow are similar to the ones espoused there. I do have my own differences however.

GUIDING PRINCIPLES

This style guide is motivated by the following guiding principles:

The code doesn't work until it looks like it works.
The code doesn't work until you've tested that it works.
Anything complex belongs in a separate function or class. Every class/function does one thing only.
Logic appears once and only once. Anything repeated belongs in a separate constant, variable, function or class.
The brain can keep track of roughly seven things at once.
If there's a small change in specifications, that should in turn generate only a small change in the code.
Minimize constructs which will cause syntax errors or bugs when more is added.
Copy and paste breeds bugs.
Anything hacked together is just a prototype. Study it and then design the real thing.
If a procedure is complex, do it every day, not once a month. Then when you need that skill in a crisis it will be easy and you won't worry about screwing up.

NAME CONVENTIONS

Standard naming conventions make it easier to pick names for variables and functions leaving the mind to solve the more challenging problem of developing the best algorithm.

PACKAGE NAMES

Package::Name -- Mixed case, capitalize word boundaries. No underscores.

Perl informally reserves lowercase module names for "pragma" modules like integer and strict. Other modules should begin with a capital letter and use mixed case, but probably without underscores due to limitations in primitive file systems' representations of module names as files that must fit into a few sparse bytes.

VARIABLE NAMES

Name describes what it contains.
Consider using a thesaurus while you program. It helps to get the right name for something.
Polymorphic variables with no known base class can be called $thing otherwise use the name of the base class or data type if nothing is more appropriate.
Avoid abbreviations especially by excluding vowels.
Allowed abbreviations: $num, $min, $max, $cols, $idx (index) $pos $ofs (offset) $fh (file handle)
No single letter variable names are allowed. $idx, $x_pos, $y_ofs are more readable and can be searched for better than $i, $x, $y
Compound names should contain the noun or thing it represents, then the adjective describing it. i.e. $page_size not $size_of_page
Ok to abbreviate when using long compound names. But if the abbreviation is obscure, put a glossary in the module description describing the full name: $html_tag
Include units in numerical quantities where appropriate. $width_cm
Name similar things consistently. Makes searches more productive.
Long distinctive names without a common prefix are preferred as a good editor will have auto-completion allowing you to type one or two letters and hit the auto-complete key to get the rest of the long variable name.
SCOPE

$global, %Global -- All globals must be prefixed by global (for scalars) or Global (for arrays)
Global variables are to be avoided in all serious code. However, in one-off scripts, they can be used. Consider using a single global hash though, as this is much easier to examine in a debugger than adding many variables to the watch window.
Avoid package local variables which are meant to be used by client code, use an accessor method instead
$Package::_our_private -- Package variables used internally by a class should be prefixed with _our_.
$lexical_name -- Lexical variables used in functions and methods appear with no special prefix.
$_protected_lexical -- Use _ to prefix a privately scoped lexical used in a closure. see example

CONSTANTS

$CONST_NAME -- Constants are written all in upper case with _ between words.
$VISIBLE preferred over $NOT_VISIBLE
or use constant TABLE_COLS => 42

SCALARS

$scalar_name -- Scalars are written all in lower case with _ between words.
$raArray $rhHash $rcCode $rObject -- References are written in mixed case with a prefix indicating the type of the referrent. Each word boundary is capitalized.

$bytes_max -- scalar maximum bytes allowed.
$page_size -- physical size of a page.
$global_debug -- a globally scoped debug flag.
$idx -- a loop index.
$rhConfig -- a Reference to a Hash of CONFIG values.
$rhGlobalConfig -- a Reference to a globally scoped Hash of Config values.
$raItems -- a Reference to an Array of Items.
$rcSort -- a Reference to an Code block to use to SORT.
$rPage -- a Reference to an object blessed as a Page.
$self -- special case - reference to self object.
$aPage -- an alternative for an object reference.
$theSystem -- an alternative for a singleton or monadic object reference.
$_our_rSystem -- in a singleton class, the internal package variable holding the one and only instance of the System class.

ARRAYS

@ArrayName %HashName -- Regular and associative arrays are written in mixed case, capitalizing word boundaries.
In many cases, the name of an associative array can be of the form %MapX_Y.

@Fields -- array of fields.
%Files -- files in a directory.
%MapField_Idx -- map of field name to index.
%_our_Properties -- internal class-wide Property settings.

METHOD NAMES

The name of the method should describe what it does in verb noun format.
Avoid abbreviations. exceptions: Init()
function_name() -- Non-object procedures should be in lower case with _ on word boundaries.
$rObj->MethodName() -- Class and instance methods of classes should be in mixed case with capitals on word boundaries.
$rObj->property() -- Property get/set methods for classes should be all in lower case with _ on word boundaries.
$rObj->SetLayout({ ... }) -- Property get/set methods which get/set large structures can be named GetX or SetX.
is_empty() $rObj->IsEmpty() -- Boolean methods which check something should be named IsX(), HasX(), CanX(), is_x(), has_x(), or can_x()
$rObj->_Private() -- Internal methods for classes should be prefixed by _.
$rObj->OnSave() $rObj->DoCommit() -- Methods which are meant to be implemented by derived classes should be named OnX(), HandleX() or DoX().

compare_files(...) -- a procedure to compare two files.
$rRect->width() -- width property get/set for an object.
$rPage->IsLandscape() -- check if the page is in landscape mode.
$rDate->FormatString(...) -- format a date object as a string.
$self->_Init() -- internal initialization method.
OnStartTag() -- inheritable method called when a start tag is seen.
DoSave() -- inheritable method called when object should save itself.

HASH KEY NAMES

HASH_KEY_NAME -- Always use uppercase names for hash keys, so they can be used unquoted with little chance of clashing with future builtin names in perl.
Prefix hash key name with _ to indicate a key that is private or computed and not meant to be inserted by client code.

CODE LAYOUT

Each programmer will, of course, have his or her own preferences in regards to formatting, but there are some general guidelines that will make your programs easier to read, understand, and maintain.

STYLE

Opening brace on new line aligned with left of keyword.

Unless the code in the block is only one line, then can be all on same line.
Braces on their own lines, make it easy to hop up and down the file from block to block with the parenthesis match feature of most good editors.

Closing brace of a multiline block lines up with left of keyword opening the block.
Uncuddled elses.
Mark closing braces of if, while, foreach, for, BEGIN, END and sub blocks with a comment indicating the type of block, especially when several are nested.

sub function
{
   if ($true) { print; }  # a small one line block
   if (...)
   {
      while (1)
      {
      } # while
   } # if
   else
   {
      ...
   } # else
} # function()

SPACING

3-column indent. No tabs.
Space around most operators.
Space around a "complex" subscript (inside brackets or braces).
Blank lines between chunks that do different things.
No space before the semicolon.
No space between function name and its opening parenthesis.
Space after every comma and semicolon
No space around ->
Space before/after first/last parenthesis matching on current line, for inline arrays and expressions.
Space on either side of curly braces for inline blocks.
Line up corresponding things vertically, especially if it'd be too long to fit on one line anyway.

    mkdir($dir_temp, 0700) or die "$0: can't mkdir $dir_temp: $!";
    chdir($dir_temp)       or die "$0: can't chdir $dir_temp: $!";
    mkdir('tmp',     0777) or die "$0: can't mkdir $dir_temp/tmp: $!";

Line up your transliterations when it makes sense:

    tr [abc]
       [xyz];

COMMENTS

Wrap comments and code at ~75 columns wide
If commenting down the right side, start at column 35
A space after the # on a single line comment
Put a comment above a chunk, giving an overview of what the chunk does. Line the comment up with the left of the first line in the chunk.
Comments should not just repeat the logic of the code, but explain it on a higher level. Two ways to do this: Write a string of comments describing what needs to be done first, and then add the code after each comment line; when a complex block of code is written, summarize what the block is accomplishing.

  # validate function parameters
  die "error" unless defined($_[0]);
  die "error" unless ref($_[0]) eq 'HASH';

  # reverse the hash so that the values map to the keys
  local $_;
  my %ReversedMap = map { ($_[0]->{$_}, $_) } keys(%{$_[0]});

If you are coding to a publicised standard or grabbing a complicated algorithm from a book, put a comment in the code mentioning the URL(s) or book and pages used. Maintenance developers do not always know where you got the original code from and may benefit from reading the source.
Always put a comment in code that has been written an obscure way because of speed, bug workarounds, major design assumptions, backwards compatibility, or a penchant for one-liners. A good rule of thumb, you need to add a comment if your line of code has more than 5 operators/functions or complex constructs (ie @{} ?: ->[] map {} grep {} sort {} slices)

PUNCTUATION

Semicolon always present, even in "short" one-line block.

You never know when you're going to add another line to the block or need to add some debugging code to the block. When you do, you'll most likely forget to add the semicolon, causing a syntax error (= frustration). Code should always be written so you can insert/delete similar lines without causing syntax errors.

Long lines broken before an operator or after a comma.

This makes it easy to insert or move logic around in the expression without having to adjust the end of the line above. It's easier to see the start of the line and fix it, than to see the end of the line.
if ($this > 12
    && $this < 42
    || $this == 18)
{
   ...
} # if
$message = "a long message a long message a long message "
           . "a long message a long message a long message "
           . "a long message a long message a long message ";

When creating a hash, one item per line, end each line with a comma so lines can be inserted and moved around without having to keep track of that last line which has no comma.
Never omit parenthesis when calling functions and builtins. Exceptions are grep, sort, map, print.

use $x_val = function(); instead of $x_val = function; or $x_val = &function;

Functions called in this manner rely on the caller's @_ and could behave differently when copied and pasted into another subroutine. see example

Also, easy to hop around the line with the parenthesis match key in your editor.
return print reverse sort by_num values %Map;      # not nice
return print(reverse(sort by_num (values(%Map)))); # much better
  
Consider the mental welfare of the person who has to maintain the code after you, and who will probably put parentheses in the wrong place.

STRUCTURE

Perl has no switch statement but you can emulate one with any number of idioms. see example
Organize your functions logically. Higher level functions at the top. Lower level and private functions at the bottom. Group related functions together. Begin with constructor/destructor, property accessor/setter, and finally mutators, behavioural overrides.
Break your sections up with comment blocks:

#==========================================================================
# Major Division   (public/private,etc)
#==========================================================================

#--------------------------------------------------------------------------
# Minor Division   (function groups)
#--------------------------------------------------------------------------
jumping from section to section is easy, search for #=== or #--- (width of block is such that 'End' key puts cursor in column 76)
A suggested list of Major Divisions for scripts: Module Header, Command Line Parsing, Main Body of Script, Functions

Major Divisions for Classes: Module Header, Module Initialization and Cleanup, Constructor and Destructor, Public Methods, Private Methods

PROGRAMMING IN GENERAL

The most important thing is to run your programs under the use warnings pragma at all times. Don't use the -w switch on the #! line as it won't be honoured when running in Windows. You may turn it off explicitly for particular portions of code via the $^W variable if you must. You should also always run under use strict or know the reason why not. The use sigtrap and even use diagnostics pragmas may also prove useful.
Test everything using perl's Test module. Code the unit tests before you write the function, then as you implement the function the unit tests begin to succeed and you can ensure you have handled all possible boundary conditions for your function.
Use local $_ whenever you use a foreach, s///, tr/// or other operation using $_ or better yet always bind to a variable. If your function modifies $_ and is called from within a foreach which in turn uses $_ you will destroy the caller's array as a side effect unless you localise $_ see example
Don't use hard coded numbers or short strings. Define a constant.

Especially if the number is used in more than one place in the code. Use a real constant or just a variable name. In practice, numbers are forbidden to be used in calculations, always use a constant. The only exceptions are 0 and 1. Using named constants in function calls, serves to document the function call.
my ($X, $Y, $WIDTH, $WRAP) = (10, 10, 60, 1);
print_text($X, $Y, $WIDTH, "message", !$WRAP);
is self documenting as compared to
print_text(10, 10, 60, "message", 0);
No one enjoys looking at a complicated expression full of numbers, trying to figure out what number means what.

Think about reusability. Why waste brainpower on a one-shot when you might want to do something like it again? Keep functions short, having at most 7-15 lines of actual code (not counting comments.) This tends to increase code reuse.
Localize all file handles by using IO::File or by using an anonymous glob:

my $fh = do { local *FH; *FH; }; # runs under -w with no warnings

Use Carp's croak function to report errors in parameters passed into functions and die for more serious errors when using those parameters during normal operation. Use Carp::Assert
Don't use $SIG{__DIE__} = &error see why
Always check the return codes of system calls. Good error messages should go to STDERR, include which program caused the problem, what the failed system call and arguments were, and (VERY IMPORTANT) should contain the standard system error message for what went wrong. Here's a simple but sufficient example:
```
                            # name of function   args  system error
opendir($dh, $dir)     or die( (caller(0))[3] . ": $dir: $!");
```
Just because you CAN do something a particular way doesn't mean that you SHOULD do it that way. Perl is designed to give you several ways to do anything, so consider picking the most readable one. For instance

open($fh, $file_name) || die "$0: Can't open $file_name: $!";

is better than

    die "Can't open $foo: $!" unless open(FOO,$foo);

because the second way hides the main point of the statement in a modifier.

But consider also

use Fatal qw(open);
open($fh, $file_name);

On the other hand

    print "Starting analysis\n" if $verbose;

is better than

    $verbose && print "Starting analysis\n";

because the main point isn't whether the user typed -v or not.

Similarly, just because an operator lets you assume default arguments doesn't mean that you have to make use of the defaults. The defaults are there for lazy systems programmers writing one-shot programs. If you want your program to be readable, consider supplying the argument.

Don't go through silly contortions to exit a loop at the top or the bottom, when Perl provides the last operator so you can exit in the middle. Just ``outdent'' it a little to make it more visible:

    LINE:
        for (;;) {
            statements;
          last LINE if $foo;
          next LINE if /^#/;
            statements;
        }

Don't be afraid to use loop labels--they're there to enhance readability as well as to allow multilevel loop breaks. See the previous example.
Avoid using grep() (or map()) or `backticks` in a void context, that is, when you just throw away their return values. Those functions all have return values, so use them. Otherwise use a foreach() loop or the system() function instead.
For portability, when using features that may not be implemented on every machine, test the construct in an eval { } to see if it fails. If you know what version or patchlevel a particular feature was implemented, you can test $] ($PERL_VERSION in English) to see if it will be there. The Config module will also let you interrogate values determined by the Configure program when Perl was installed.
If you have a really hairy regular expression, use the /x modifier and put in some whitespace to make it look a little less like line noise. Don't use slash as a delimiter when your regexp has slashes or backslashes.
Use here documents instead of repeated print() statements.

Where it makes sense, remove leading whitespace from your here documents so they don't break up the code so much. see example

Consider generalizing your code. Consider writing a module or object class. Consider making your code run cleanly with use strict and use warnings in effect.

EXAMPLES

Demonstration of a completely private lexical variable, the only access to it is by calling the push() or pop() method.

{ # begin a scope to limit access to lexical
  my @_Stack;
  sub push { push(@_Stack, @_[0]); };
  sub pop  { pop(@_Stack); };
} # end of lexical scope

Example how function call can misbehave if you omit the () when calling it.

f(qw(apple orange));

sub func
{
   my $x = shift;
   print "x: " . ($x || 'undef') . "\n";
}

sub f
{
   func;    # x: undef
   &func;   # x: apple  -- weird
   func();  # x: undef
   &func(); # x: undef
}

Many ways to write a switch statement.

SWITCH:
{
   local $_; # just in case you muck with it

   if    (/^abc/) { ...; last SWITCH; }
   elsif (/^def/) { ...; last SWITCH; }
   else           { die "never"; }
} # SWITCH

SWITCH:
{
   local $_; # just in case you muck with it

   /^abc/     && do { ...; last SWITCH; };
   /^def/     && do { ...; last SWITCH; };
   die "never";
} # SWITCH

foreach ($some_long_name_or_expression)
{
   /abc/      and do { ...; last; };
   /def/      and do { ...; last; };
   die "never";
} # foreach

for ($some_long_name_or_expression)
{
   $value   = /red/   ? 0xff0000 :
              /green/ ? 0x00ff00 :
              /blue/  ? 0x0000ff :
                        0x000000 ; # black if fail
} # for

Inadvertent trashing of an array.

use Data::Dumper;

my @Array = qw(THIS IS A TEST);

foreach (@Array)
{
    ff();
}

sub ff
{
   while (<STDIN>)
   {
     # @Array is now dead
   }
}
print Dumper \@that;

ff()

local $_

while

while (my $line = <STDIN>)

If you make use of $SIG{__DIE__} = &error you will have to do:

eval { local $SIG{'__DIE__'}; $SIG{'__DIE__'} = '' if $SIG{'__DIE__'};
  ...
};

sub main
{
   eval
   {
      ... main program
   };
   error($@) if ($@);
} # main()

Indented here documents.

print dequote(<<"EOF");
    | Attention criminal slacker, we have yet
    | to receive payment for our legal services.
    |
    |     Love and kisses
    |
EOF

print dequote(<<'FOO');
        Attention, dropsied weasel, we are
        launching our team of legal beagles
        straight for your scrofulous crotch.

                xx oo
FOO

dequote()


sub dequote {
   local $_ = shift;
   my ($white, $leader);  # common white space and common leading string
   # Look at first and second line, to find a common prefix string
   if (/^\s*(?:([^\w\s]+)(\s*).*\n)(?:\s*\1\2?.*\n)+$/)
   {
      ($white, $leader) = ($2, quotemeta($1));
   } # if
   else
   {
      # no common prefix, strip all leading whitespace
      ($white, $leader) = (/^(\s+)/, '');
   } # else
   # Now manipulate each line of the string by stripping the leadin
   s/^\s*?$leader(?:$white)?//gm;
   return $_;
} # dequote()

REFERENCES

CPAN Perl Style Guide: http://www.perl.com/CPAN-local/doc/manual/html/pod/perlstyle.html