Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Coding Standards

schwern edited this page · 10 revisions

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

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.

Something went wrong with that request. Please try again.