Perl Coding Standards

Purpose

See the C++ Coding Standards for the general purpose of Standards.

After doing Code Reviews with C++ for a while, there occurred the wish among Perl developers to do code reviews as well and to set up a rule set for that purpose.

The following is a first draft of those.

Rules for Perl

General

Strict Settings (Strict)

Apply use strict and use warnings to all scripts and modules.

Design

Make Functions Short (Short)

Make functions short. A comment line or large control structures are hints to extract functions, making the containing function more concise and readable.

Avoid Duplicate Code (Dupli)

Avoid and remove duplicate code. Put common code into an extra function.
Duplicate code may be okay, if otherwise dependencies among so far unrelated modules would be created.

Use Framework Classes (Reuse)

Use the modules provided in a standard Perl 5.8 installation instead of reinventing the wheel.
However, don't create new dependencies to uncommon Perl modules, if there is no major need.

Use Perl Functions (PerlFs)

Prefer perl functionality over calls to system() where possible.

Optimize Sensibly (Opti)

Optimize by algorithm complexity.
Don't do smaller optimizations, if they make the code less readable and there is no proven reason.

Declarations: Scoping and Names

Use my (My)

Use my to scope all variables local to a block.

Avoid Global Data (NoGlobal)

Use as few global data as possible.

Assign Parameters at Top (Params)

Assign all parameters of a function to local, sensibly named variables on top of the function body.

Descriptive Names (Descr)

Use descriptive names.

Naming Conventions (NameConv)

Adhere to naming comventions:

• filehandles in capital letters: MYFILE
• start class names with a capital: MySelfmadeModule
• prefere underscores instead of mixed cases for variable names: multipart_name

Recommendation: use ref postfix for references

Implementation Details

Explicit Returns (Return)

Use an explicit return statement for every return.

Use Parentheses(Paren)

Use parentheses for all function calls.

Possible exceptions: standard perl idioms.

Close Handles Soon (Close)

Don't forget to close all filehandles and connections. Close them as soon as possible.

Near Backinserters (BackIn)

Use and assign regular expression backinserters (like ($1), ($2)) as close to the originating expression as possible, never more than five lines away.

Check System Calls (System)

Check the return values of all system calls.

Use the Correct Comparison Operators (Compare)

Make sure, eq etc. are used for strings and == etc. for numbers.

Pathseparator is Slash (Path)

Use the forward slash as path separator in all cases.

Exception: When a system program needs a path in local convention as argument.

Comments

Comments (Comments)

Use enough comments in the code to make it understandable.

Document Function Behaviour (ClearBehave)

As far as the behaviour of a function is not clear by its name and parameters, document that behaviour.

Document Return (DocReturn)

If a function has a non-obvious return semantic, document type and semantic of the possible return values.

---