Perl Coding Guidelines
======================

Core Guidelines
===============

1) Always use the 'strict' pragma. 
This prevents the use of unsafe constructs in perl scripts and requires
all variables to be lexically scoped or fully qualified. It also restricts
the use of symbolic references and bareword identifiers that are not
subroutines, hence reducing the debugging time for a very tricky class
of bugs.

2) Always use the 'warnings' pragma.
The same can be achieved by invoking the perl interpreter with the '-w'
switch. This prints warnings about possible spelling mistakes and other
constructs that are prone to error. Both the 'strict' and 'warnings'
pragmas will ensure a certain degree of quality in the code and reduce
the number of errors.

3) Use proper indentation.
Properly indented code is easy to maintain and debug. Every subsequent
level must be indented by the same amount (usually 4 columns) and must
maintain that consistency throughout. The source code could optionally
be filtered through a utility such as 'indent' on UNIX to ensure that
the consistency is maintained.

4) Document everything.
Every method should be documented properly, either inlined or in POD
(Plain Old Documentation) format. The documentation should capture
the purpose and scope of the application and must be included for each
publically acessed method or subroutine.

5) Write proper unit tests.
All code is susceptible to bugs and its mandatory that every program be
be associated with its own unit tests.

6) Be consistent when naming modules, methods and variables.
The name should reflect the functionality of the module and must be
descriptive.

> Constants must be in $ALL_CAPS.
> Global/package scoped variables must begin with an uppercase letter
  and use underscores or BiCapitalization to separate words.
> Lexically scoped variables must begin with a lowercase letter and use
  underscores or BiCapitalization to separate words.
> Function and method names are named similar to lexically scoped
  variables. Functions beginning with an underscore are considered private.


Typographic Guidelines
======================

1) The opening curly brace of a multi-line block should be on the same
line as the keyword and must contain a preceding space.

2) No space before the semicolon.

3) Space around most operators.

4) Blank lines between chunks that do different things.

5) No space between function name and the opening paranthesis.

6) Space after each comma.

7) Long lines broken _after_ an operator except in the case of "and"
and "or".


General Guidelines
==================

1) Keep things simple.
Its better to have a set of small sub routines than a monolithic one. It
enhances readability and gives additional flexibility and opportunity
to reuse. A subroutine with more than 100 lines should probably be
refactored to be made smaller.

Perl being a very flexible language allows the programmer to solve a
given problem in wide variety of ways and therefore the simplest and
most readable solution should be given high priority.

2) Always return a value explicitly.
Perl implicitly returns $_ for conveniency, which can lead to strange
hard to debug error conditions, so its advisable to return the values
explicitly, avoiding multiple return points if possible.

3) Do not hardcode.
Hardcoding can lead to difficult-to-maintain code, so its advisable to
use constants, for instance, defined at the beginning of the program,
rather than embedding them in the code directly.

4) Separate functionality from presentation.
Code that focuses on functionality should not have to deal with the
eye-candy of presenting it. This allows one to exist independently of
the other and reduces code complexity. For example, avoid having to put
markup directly in the code. Use an appropriate templating library to
achieve it cleanly.

5) Use named parameters wherever possible.
Its easier to use the following construct :
	method_name(key1 => "value1", key2 => "value2");
Rather than :
	method_name("value1", "value2");

The order of the parameters can also be changed easily in the named
parameter approach and new parameters can be added without having to
change existing code.

6) Warn or Carp messages to console.
On encountering erroneous conditions that need to be notified, its always
good to warn() or carp() them to the Standard Error stream on the console.

7) Avoid global variables.

8) Use eval() to trap errors.
On constructs that are proned to failure, use eval() to execute and trap
the error condition and inform the user or take proper action to remedy
the situation. Use warn() to send warning messages to STDERR indicating
error conditions.

9) Parse commandline arguments.
Scripts intended to run on the console should parse commandline arguments
and provide support for at least --version and --help arguments and
provide usage hints if the provided arguments are incorrect.

10) Use paranthesis to aid readability.
If you are unsure of operator precedence or just not sure of the order
an expression will be evaluated, always use paranthesis.

11) Use /x modifier in regular expressions.
To make regular expressions more readable, use the /x modifier to put
in line breaks and comments.

12) Use single quotes where interpolation is not required, as they are
more efficient.

13) Always check the return codes of system calls.

-----
Anuradha Weeraman, 07 Mar 2004