Tilt API Style Guide

This style guide is a general style guide for our API perl coding practices and standards. For more specific current best practices on specific features or areas of the codebase, see the corresponding .md file in this repo for more info on that topic.

Table of Contents

• General Perl – Best practices for Perl, our API's main language
• Function Signatures - Best practices for function/method signatures
• Moose – Best practices for Moose, our object system
• DBIC – Best practices for DBIx::Class, our ORM library
• Tests – Best practices for our prove and TAP based test harnesses
• Postgres – Best practices for PostgreSQL and PL/pgSQL, our RDBMS

General Perl

Follow the jQuery style guide

The following rules take precedence over the jQuery guide:

• Adhere to a strict 80-character line length.
• The jQuery style guide calls for loose parens, but this optional. Use your discretion and maximize readability.
• Try to add as few lines of code as possible without sacrificing readability.
• Be conservative with vertical space. Avoid two or more blank lines in a row.
• Indent with spaces, not tabs. 1 indentation level = 4 spaces.
• Variable and function names should be lower_case_with_underscores.
• Vertically align multiline key/value pairs. Add a trailing comma to every line.
• Avoid unnecessary line noise, where line noise is defined as code that =~ /\W/
• Avoid nesting ternary operators.
• Prefix methods that return booleans with is_, has_, or can_ (depending on context)
• Do not rely on or write boolean methods to always return an integer (e.g. 0/1). They may return any truthy/falsey value, e.g. 42 or ''

Always use tilt::core

tilt::core gives us a robust set of baseline Perl modules, pragmas, and features, and we should always be importing this module first.

use tilt::core;

However, if another module that alters the current file with a custom DSL (Domain-specific language) is loaded first, such as Dancer or Moose, then that module should take precedence.

use Dancer;
use tilt::core;

...

dance;

Favor strict mode