Coding Standards

How To Change This Document And Our Style

• Non-policy changes, typos, wording, formatting and such, can be done by anyone.
• Policy changes should be submitted as an issue.
• Changes to .perlcritic and .perltidy can be done as pull requests.
• Not sure what to do or what something means? Ask.

Checking and Correcting Style

• Anyone can correct the code to better match style.
• Syntax style is codified in .perltidy.
• As much coding style as possible is codified in .perlcritic
• Running ./Build tidy and ./Build critic will run perltidy and perlcritic respectively.

Testing

• t/00_TEST_TEMPLATE.t is a template for writing tests. Copy it to make new test files.
• Tests should use Test::Most, with no test count specified.
• Tests should use perl5i::latest, not perl5i::2. This will make creating a new major version easier.
• Tests should have a #! line.
• Each test file should test a single method or group of related methods, or a single, complicated bug.
• Tests which require complicated set up should go in their own test file.
• Sets of related test files should go into a sub-directory.
• perl5i specific testing libraries should go into t/lib

Coding

• The documentation does not have a version number, for example lib/perl5i.pm and lib/perl5i/Meta.pod.
• The code has a major version, for example lib/perl5i/2.pm and lib/perl5i/2/HASH.pm.
• If it applies to all things (blessed objects and regular data) it goes into perl5i::2::Meta::Instance.
• If it applies to all data (ie. lists, scalars, hashes, etc...) it goes into perl5i::2::UNIVERSAL.
• To reduce our load time, require modules inside the methods which need them.

Interfaces

• Error is indicated not by returning false, but by throwing an exception.
• If a method takes options they should be supplied by a hashref. We haven't been consistent on this in the past and may change in perl5i::3.

Defaults

Methods must have a defined default behavior OR throw an exception if a required argument is missing.

Default behavior must be documented.

Here's an example...

   wrap

       my $wrapped = $string->wrap( width => $width, separator => $separator );

   Wraps $string to $width characters, breaking lines at word boundries using
   $separator.

   $width defaults to 76.  The default $separator is the newline character "\n".

Should a method have a default?

A method should have a default if you asked a normal human to do the task and they wouldn't ask any further questions about it. You can determine this with a short conversation with yourself.

For example, 12.1->round...

Alice: Round 12.1 please.
Bob:  12

See how one doesn't have to ask "to what precision" or "up or down". Even though these are rounding options, humans, on a regular basis, round in one way.

Contrast with ["foo", "bar", "baz"]->join...

Alice:  Join "foo", "bar", and "baz" together.
Bob:  Join them with what?
Alice:  Commas.

Alice could have equally likely said "spaces" or "tabs" or "nothing". Good indicator that join should not have a default.