Perl6 Style Guide

This is the Zysys Perl6 Style Guide. This covers most of Perl6, but because Perl6 has not yet been fully implemented, it may change with time.

The idea of this document is to outline the set of rules that can be followed to create code that is straight-forward, yet simplistic and clear. The decisions were made with focus toward understanding what the program was doing faster at first glance. Individual decisions are not going to be explained as this document was originally created for Zach Bornheimer's personal use.

Zysys Perl6 Tutorials

Perl6 Tutorials are floating about...perl6 is used so infrequently at Zysys and perl6 is so young in implementation, the tutorials may be out of date. Zysys Perl6 Tutorials

Case

  • Variables : camelCase
  • Subroutines & Methods : lowercase_with_each_word_separated_with_an_underscore
  • Grammars & Constants : TitleCase
  • Blocks : CAPITALIZED

Methods vs Subroutines

  • Use methods on objects
  • If the target of the sub/method is the data, use a method. If it is not (as in say), use a subroutine.
Example:

 my @alpha = <this is a test list>;
 my @beta = @alpha.uniq; # Better than: my @beta = uniq @alpha;
 say @alpha.perl;
 # say modifies the STDOUT, not the data, so use a sub (see [[Parentheses][Parentheses]] for why there are not parens)
 #'perl' modifies a copy of the data @alpha so it is a method

Parentheses

  • Use parens around user-defined subs
  • Use parens all methods if an argument is given
  • Use parens for clarification (Note that a string of methods is easier to read than a bunch of parentheses)
  • Use parens in an if loop to clarify negation:
if !($checkSomething) {
    # Do Something
}
  • Do not use parentheses for built-in subroutines
  • Do not use parentheses around loop arguments as they are arguments to a built-in subroutine. Only use parens to make the code clearer.

Postfix If

  • Use postfix if only when the conditional will only modify one line AND will make the code clearer.
if ($debug == 1) {
    print "DEBUG_STATE ON";
}

would best be written as:

print "DEBUG_STATE ON" if ($debug == 1);

This example doesn't fully demonstrate the choice. If there was a sequence of $debug value checks, the code would be clearer if written similarly to a switch, however, the semantic focus of the line was that "DEBUG_SATE ON" gets printed if the $debug flag is set to 1, thus we programmed that instead of: if the $debug flag is set to 1, print "DEBUG_STATE ON"

Redundant Code

  • Do not use redundant code. Instead create a subroutine or use a loop to remove the redundancies.
my @alpha = <this is a test array>;
my @beta = <beta can be an array too>;
my $gamma = @alpha.item; # this designates $gamma as a reference to @alpha;
for (0 .. 1) -> $iterator {
    @$gamma.pop();
    $gamma = @beta.item if $iterator == 0;
}

When use Subroutines Straight Coding

  • When you to make code reusable
  • When an algorithm is very complex or long, it should live on it's own for debugging purposes
  • When you cannot efficiently display the flow of the program because the code is too complex (it would probably be good to write a BEGIN block with the subs called right away).

Comments

  • Code should be written well enough that comments are not necessary for someone who knows the language
  • Write comments that describe data structures,
  • Write comments that describe the purpose of subs and methods
  • Write comments that clear up any possible questions that might arise from your code
  • Use POD to document API's or anything that an enduser might want to see as documentation for the software (like the purpose of the software, author, license, etc.)

Grammars

  • Any rule greater than 5 characters gets to be on it's own line.
  • Use proto tokens for clarity as opposed to multiple unnecessary tokens
grammar TestGrammar {
    rule TOP {
        <symbol><code>
    }
    proto token symbol {*}
    token symbol:sym&lt;+&gt; { <sym> }
    token symbol:sym&lt;--&gt; { <sym> }
    token code:sym<alpha> { <sym> }
    token code:sym<beta> { <sym> }
}
Edit | Attach | Watch | Print version | History: r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r2 - 2014-12-28 - ZachBornheimer
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback