The Low-Magic Perl Commandments

Rules For Faster Perl.

Free & Open Source on GitHub

The Low-Magic Perl Commandments

Last Update: December 10th, 2016

Feelings

“Sam sat on the ground and put his head in his hands.
'I wish I had never come here, and I don't want to see no more magic,' he said, and fell silent.”
~ JRR Tolkien, The Fellowship Of The Ring

Best Practices

“Each piece of advice is framed as a single imperative sentence – a 'Thou shalt...' or a 'Thou shalt not...'
People cling to their current coding habits even when those habits are manifestly making their code buggy, slow, and incomprehensible to others.
Recorrect each old habit the instant you notice yourself backsliding. Be strict with your hands.”
~ Damian Conway, Perl Best Practices

Table Of Contents

Ideals
Magic
Data
Operations
Object-Orientation

Ideals

THOU SHALT:THOU SHALT NOT:
0. Use Perl & Have No Other Programming Languages Before Perl 1. Use Non-Perl Programming Languages, Except During Official Emergencies
2. Use Perl Best Practices (“perlcritic –brutal” & “perltidy -pbp”) & Idiomatic Programming 3. Use Cleverness, Obfuscation, Golf, Or Non-PBP Code, Except As Officially Stated Herein
4. Use Diligence To Create Robust, Effective, Bug-Free, High-Quality Code That Serves A Real Need 5. Use Laziness To Create Fragile, Ineffective, Buggy, Low-Quality Code That Just Saves Labor
6. Use Patience To Create Efficient, Fast Code That Does Its Job 7. Use Impatience To Create Inefficient, Slow Code That Does More Than Its Job
8. Use Humility To Create Maintainable, Re-Grokkable Code That Serves The Greater Good 9. Use Hubris To Create Unmaintainable, Incomprehensible Code That Just Impresses People

Magic

THOU SHALT:THOU SHALT NOT:
10. Use & Contribute To Low-Magic Pure-Perl CPAN Code 11. Use XS, High-Magic Perl, Or High-Magic CPAN Code, Except During Official Emergencies [PBP 228 Conflict]
12. Use Pragmata To Mark Magic Level Of Code (“use magic;” & “no magic;”) 13. Use Unmarked High-Magic Code
14. Use Production Perl Features 15. Use Deprecated (Array Value Exists, etc) Or Experimental Perl Features (Lvalue Subroutines, Attributes Pragma, etc)

Data

THOU SHALT:THOU SHALT NOT:
16. Use A Type System, Static-Type Data, Variable Declarations, & Non-Tied Variables 17. Use Dynamic-Type Data, Auto-Vivification, Or Tied Variables
18. Use Private Lexical-Scope Variables (“my”) 19. Use Private Dynamic-Scope (“local”), Private Persistent Lexical-Scope (“state”), Global, Or Package Variables (“our”)
20. Use Scalars, Arrays, Hashes, Filehandles, & Mundane Lvalues (Variables & Slices) 21. Use Typeglobs, Code References, Weak References, Or Magic Lvalues (Builtins, Non-Variables, Non-Slices, etc)
22. Use Normal Variables With Single, Descriptive Names 23. Use Aliased, Non-Descriptive, Special ($1, $a, %ENV, %SIG, etc), Or Punctuation Variables ($_, @_, %!, $@, $$, etc)
24. Use Direct Access To $ Scalar Variables 25. Use Indirect Access To $ Scalar Variables Via References Or Pointer Arithmetic
26. Use Indirect Access To Arrays & Hashes Via Anonymous References Stored In $ Scalar Variables 27. Use Direct Access To Arrays & Hashes Stored In @ Or % Non-Scalar Variables
28. Use Numeric & Single-Quote Non-Interpolated String Literals 29. Use Double-Quote Interpolated String Or Special Literals (__FILE__, __LINE__, __PACKAGE__, __SUB__, etc)
30. Use Mundane @ARGV & Known Constants (“use constant PI => my number $TYPED_PI = 3.141_59;”) 31. Use Magic @ARGV, Magic Numbers, Or Secret Constants (Amphisbaena, Space Fleet, etc)
32. Use Definedness Test On Builtins (“defined( $var = builtin $args );” Or “defined( builtin $args );”) 33. Use Undefined Values (“$var = undef;”, etc) Or Definedness Test On Non-Builtins (“defined($var);”, etc)
34. Use Secure Platforms & Trusted Data 35. Use Taint Mode

Operations

THOU SHALT:THOU SHALT NOT:
36. Use Compile-Time Includes (“use MyModule;”) 37. Use Run-Time Includes (“require MyModule;”)
38. Use Static-Type Arguments & Return Values For Subroutines 39. Use Dynamic-Type Arguments Or Return Values For Subroutines
40. Use Static Number Of Arguments & Single Return Values For Subroutines 41. Use Dynamic Number Of Arguments, Multiple Return Values, Or Dynamic Context (“wantarray”) For Subroutines
42. Use Real Prototypes (“our integer_arrayref $f = sub {(my string $x, my integer $y) = @ARG; ...};”) 43. Use Perl Prototypes (AKA Parameter Context Templates)
44. Use Basic String Processing 45. Use Regular Expressions, Smart Match, q Quoting Mechanisms, Unicode/UTF-8, Or String Interpolation
46. Use Conditional & Loop Control Structures, Including Flow Control Statements (next, last, redo, etc) 47. Use Goto, Either Mundane (“goto MYLABEL;”) Or Magic (“goto &mysub;”)
48. Use Normal Code Blocks (Bodies Of Conditionals, Loops, & Named Subroutines) 49. Use Special Code Blocks (Closures, Anonymous, BEGIN, UNITCHECK, CHECK, INIT, END, etc)
50. Use Early Binding (Compile-Time Dispatch) & Eager Evaluation (Compile-Time Compile) 51. Use Late Binding (Autoload, Run-Time Dispatch, etc) Or Lazy Evaluation (“eval”, Promises, Run-Time Compile, etc)
52. Use Lexical-Scope Grep & Map (“map { my int $var = $_; foo($var); } @{$vars};”, $_ Allowed) 53. Use Dynamic-Scope Grep Or Map (“map { foo($_); } @{$vars};”, $_ Disallowed)
54. Use Mundane Open (“open my $fh, '>', $filename;” Or IO::File) & Non-Preprocessed Code 55. Use Magic Open (“open my $fh, '-|', @program;”) Or Preprocessed Code (Source Filters, etc)
56. Use Operations In 1 Context (Scalar Or List) & Scalar Operations On 1 Type (Number, String, etc) 57. Use Scalar Operations In List Context & Vice-Versa, Or Numeric Operations On Strings & Vice-Versa
58. Use Unique Subroutine Names & Known Builtins 59. Use Overloading Or Secret Operators (Diamond, Spaceship, Babycart, Bang Bang, Enterprise, Space Station, etc)
60. Use Lexical-Scope & Non-Complex Builtins 61. Use Global-Scope (“select”, etc) Or Complex Builtins (“format/write”, “pack/unpack” [PBP 102 Conflict], etc)

Object-Orientation

THOU SHALT:THOU SHALT NOT:
62. Use Low-Magic OO (Blessed Reference To Field Hash Or Restricted Hash [PBP 195 Conflict]) 63. Use High-Magic OO (MOP, Moose, Mouse, Moo, etc)


External References