Code Style

Here are the code style guidelines. You may violate them if doing so will produce more readable code FOR ALL (not just you).

Your editor/fingers/terminal not supporting this style is not an excuse. It's 2011, adapt your editor/fingers/terminal.

The Basics

Follow these basics and you'll be fine.

• 4 character indentation.
• NO LITERAL TABS
  • unless inside a string, then use your discretion
• Unix newlines.
• Max 100 characters wide.
• When in doubt, follow Perl Best Practices.

Naming

Use this_style_of_naming.

Variable Names

• $local for single subroutine lexicals
• $Global for multi-subroutine lexicals and globals
• $CONSTANT for constants

Method Names

• _private()
• public()

Blocks

Block style for simple conditions:

  if( condition ) {
      code
  }
  else {
      code
  }

Complex conditions:

  if( condition              or
      another condition      or
      yet another condition           
  ) {
      code
  }
  else {
      code
  }

Parens

The paren is attached to the enclosing element...

  function( args )

...unless it makes it clearer to do otherwise.

  $obj->method                ( args );
  $obj->another_similar_method( args );

Horizontal Whitespace

Use horizontal whitespace to make similar things look the same, and vice-versa.

For example, line up related assignments.

$person{name}          = "Yarrow Hock";
$person{rank}          = "Rear Admiral";
$person{serial_number} = 123456;

$food = "bagel";

Line up hash constructors.

my %person = (
    name                => "Yarrow Hock",
    rank                => "Rear Admiral",
    serial_number       => 123456
);

Vertical Whitespace

Please use extra vertical whitespace to help differentiate between logical code elements.

• Place two blank lines between subroutines.

• Place blank lines between logical hunks of code.

  if( thing ) { 
      some code
  }
  
  $obj->some_method;
  
  if( other thing ) {
      other code
  }
  

Compatibility

All documented functionality must remain backwards compatible unless you get explicit permission from Schwern.

Pre 2.00 must work with all versions and configurations of Perl from 5.6.1 forward on all operating systems.

2.00 is compatible back to 5.8.1 (possibly moving to 5.8.8).

Dependencies

There can be no build or run-time dependencies beyond the existing ones and what ships with Perl.

perltidy

We like perltidy, but in small doses. There is a perltidyrc checked in. Use that and improve it, but please do not apply to the entire source code as there is too much careful formatting.

perlcritic

Similar philosophy to perltidy. There is a perlcriticrc checked in and a make perltidy.