IEPM Perl Coding Styles

Overview

This document serves as a guideline for the formatting of Perl code for use within the IEPM department. The use of consistent formatting and helpful documentation of code will ease development, faciliate debugging and enable collaboration of code.
Due to the numerous styles by which people code and formatting text, it is currently recommended that the lead author (or designated maintainer) of the code in question specified the desired code style for that perl script/module only.

This is a temporary solution from which we as a group must determine the best practise code styles from which we can base future decisions on code formatting which will be suitable for us as a group. In time, we expect to learn from each others code styles to learn the benefits and disadvantages of each and therefore evolve to a standard code style.

Code which will be distributed to others not of our group, should be formatted under the recommended perl formatting specifications as defined in Perl Style Guide.

PerlTidy

To ease formatting and translations of the various coding styles available, it is recommended that the tool PerlTidy should be used to (re)format code to the format desired.

The idea is to (re)format code to the desired style for editing and or distribution. However, as suggested above, the code should be formatted to the desired code style of the code maintainer/author.

Usage

PerlTidy is available on all AFS enabled machines at SLAC. The basic syntax is

    perltidy [ options ] file1 file2 file3 ...
    perltidy [ options ] file1 -o outfile
    perltidy [ options ] file1 -st >outfile
    perltidy [ options ] outfile

Unless outfile is defined, the (re)formated output is saved to file.tdy. It is possible to overwrite the existing input file with the perltidy output using the -b option.

Installation

In order to utilise the styles defined in this document, the PerlTidy configuration file needs to be added to your home directory. It is suggested that the file is symlinked to support version changes as we redefine the styles as a group.

Run the command:

$ ln -s /afs/slac.stanford.edu/g/scs/net/netmon/perl/.perltidyrc ~/.perltidyrc

Styles

PerlTidy supports user definable profiles that enable easy changing of perl code styles. Three styles are currently in use at SLAC, and they can be applied to existing code using the following commands.

H5. IEPM Style 1

$ perltidy -iepm_style1 file
# simple example perltidy script
my $input = <STDIN>;
if ( open( FILE, "<$input" ) )
  { while ( $file = <FILE> )
      { # pointless loop!
        for ( my $i = 0; $i < 100; $i++ ) { print "."; }
        print "\n";
        push( @entries, $file );    # copy contents of file to memory
        $count++;                   # keep a counter
      }
    close(FILE);
  }
else
  { die "Could not open file $file: $!\n";
  }

IEPM Style 2

$ perltidy -iepm_style2 file
# simple example perltidy script
my $input = <STDIN>;
if (open(FILE, "<$input")) {
  while ($file = <FILE>) {
    # pointless loop!
    for (my $i = 0; $i < 100; $i++) { print "."; }
    print "\n";
    push(@entries, $file);    # copy contents of file to memory
    $count++;                 # keep a counter
  }
  close(FILE);
}
else {
  die "Could not open file $file: $!\n";
}

IEPM Style 3

$ perltidy -iepm_style3 file
# simple example perltidy script
my $input = <STDIN>;
if ( open( FILE, "<$input" ) )
{
    while ( $file = <FILE> )
    {
        # pointless loop!
        for ( my $i = 0; $i < 100; $i++ ) { print "."; }
        print "\n";
        push( @entries, $file );    # copy contents of file to memory
        $count++;                   # keep a counter
    }
    close(FILE);
} ## end if ( open( FILE, "<$input"...
else
{
    die "Could not open file $file: $!\n";
}

Perl Recommended

$ perltidy file
# simple example perltidy script
my $input = <STDIN>;
if ( open( FILE, "<$input" ) ) {
    while ( $file = <FILE> ) {

        # pointless loop!
        for ( my $i = 0 ; $i < 100 ; $i++ ) { print "."; }
        print "\n";
        push( @entries, $file );    # copy contents of file to memory
        $count++;                   # keep a counter
    }
    close(FILE);
}
else {
    die "Could not open file $file: $!\n";
}