Perl Coding Guidelines v1.08

1. Introduction

This document provides guidelines for coding in Perl for BBC website projects. Following these guidelines encourages clarity and readability in code and avoids idioms that can give rise to common bugs. The specific requirements that your Perl code must meet can be found in the (Server-side) Application Development Guidelines , which will be available to you after a Non-Disclosure Agreement has been signed.

Top of page

2. General standards

You SHOULD use the standards from the "Perldoc perstyle" guide, but with some important differences as discussed here.

Top of page

3. Reusability and modularisation

3.1. We prefer object-oriented reusable code, but this is not required. Whenever suitable, you SHOULD consider generalising code and writing modules or object classes.

3.2. You SHOULD use subroutines, which are no longer than 100 lines, wherever possible. A subroutine longer than that SHOULD be refactored, as this is likely to make it clearer and easier to maintain.

Top of page

4. Comments

You SHOULD write copious comments, both for POD (plain old documentation) and other comments, wherever something may not be obvious.

Top of page

5. KISS

5.1. KISS: Keep It Short & Simple. Perl is designed to give you several ways to do anything – you SHOULD always pick the most readable one.

For instance,

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

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.

On the other hand

print " Starting analysis\n" if $verbose;

is better than

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

because the main point is not whether the user typed -v or not.

5.2. When operators let you assume default arguments, you SHOULD supply the arguments explicitly, to aid the readability of your code.

5.3. Similarly you SHOULD use parentheses in code to aid readability. For example, the second of these is easier to follow:

return print reverse sort num values %array;

return print(reverse(sort num (values(%array))));

Top of page

6. Variable and function names

6.1. The names of your variables and subroutines are a good way to communicate the meaning of your code to other developers who have to read and maintain it. Therefore all identifiers SHOULD be descriptive.

6.2. Function and method names adhere to the same standard as Local variables – they SHOULD begin with a lower case letter. You SHOULD also separate words with underscores or studly caps.

6.3. Function names beginning with an underscore are considered private, and SHOULD NOT be called outside of the package in which they are defined.

Top of page

7. And – Or

You SHOULD understand the difference between the and and or operators. Use them appropriately avoid excessive parenthesise list operators and to reduce the incidence of punctuation operators like && and ||.

Top of page

8. Document history

Date	Version	Change	Author
02/03/2005	v1.08	Removed MUSTs and put them into Application Development Guidelines; Changed this doc to a guideline instead of a standard.	Sally Underwood
04/03/2003	v1.07	Added bookmarks to all headings for easier reference from browser	Jonathan Hassell
19/08/2002	v1.06	Added audience into footer	Jonathan Hassell
17/08/2002	v1.05	Checked all contacts are abstracted into contacts file	Jonathan Hassell
16/08/2002	v1.04	Renamed as appendix A. Checked all inter-document links	Jonathan Hassell
15/08/2002	v1.03	Done global search for MUST, SHOULD etc.	Jonathan Hassell
12/08/2002	v1.02	Reworked language to comply with RFC 2119 (as requested by MattB)	Jonathan Hassell
07/08/2002	v1.01	Added copyright information to footer	Jonathan Hassell
06/08/2002	v1.00	Moved much of this documentation from old App3	Jonathan Hassell

Top of page