Clone this wiki locally
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
./Build criticwill run
- 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
- 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.
- 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.
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.
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.
["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.