The document discusses the author David M. Bradford's perspective on writing maintainable Perl code, particularly addressing the misconception that Perl is a 'write-only' language. It emphasizes the importance of readability and maintainability in coding, showcasing the function 'listify' as an example, along with its enhancements and refactoring suggestions. The document also highlights various coding practices and tools like Perl::Critic to improve code quality.

1. Writing Maintainable Perl
David M. Bradford

2. Who am I?
David Bradford
@tinypig
tinypig.com

3. Who am I?
● Web Engineer at OmniTI
– Full stack tech consulting
– Remote database management and consulting
– Large Scale / Mission Critical
– We're Hiring!
– omniti.com

4. Why This Talk?
● Is Perl a "write-only" language?

5. Why This Talk?
● Is Perl a "write-only" language? No!

6. Why This Talk?
● Is Perl a "write-only" language? No!
● ...but it can be.

7. Why This Talk?
● Is Perl a "write-only" language? No!
● ...but it can be.
● It's our responsibility to keep code:

8. Why This Talk?
● Is Perl a "write-only" language? No!
● ...but it can be.
● It's our responsibility to keep code:
– Easy to read

9. Why This Talk?
● Is Perl a "write-only" language? No!
● ...but it can be.
● It's our responsibility to keep code:
– Easy to read, so it will be:

10. Why This Talk?
● Is Perl a "write-only" language? No!
● ...but it can be.
● It's our responsibility to keep code:
– Easy to read, so it will be:
– Easy to maintain

11. My Function, “listify”
sub listify {
my ($aref,$cc) = @_;
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
my $j;
for(my $i=0; $i<=$#$aref; $i+=$cc) {
push @$j, [@$aref[$i..$i+$cc-1]];
}
$#{$j->[$#{$j}]}=$#$aref%$cc;
@$aref = @$j;
return 1;
}
return;
}

12. Purpose of listify
Take a list, for example:
List # 1, with 10 items
one two three four five six seven eight nine ten
Give me several lists back, each containing no more than N items,
for example, 4:
List #1 with 4 items: one two three four
List #2 with 4 items: five six seven eight
List #3 with 2 items: nine ten

13. Prepare to call listify
listify( @list, 4 );
Result:
@array = (
[ 'one', 'two', 'three', 'four' ],
[ 'five', 'six', 'seven', 'eight' ],
[ 'nine', 'ten' ],
);
my @list = qw( one two three four five six seven eight nine ten );

14. Call to listify
my @list = qw( one two three four five six seven eight nine ten );
Result:
@array = (
[ 'one', 'two', 'three', 'four' ],
[ 'five', 'six', 'seven', 'eight' ],
[ 'nine', 'ten' ],
);
listify( @list, 4 );

15. Result of listify
my @list = qw( one two three four five six seven eight nine ten );
listify( @list, 4 );
Result:
@array = (
[ 'one', 'two', 'three', 'four' ],
[ 'five', 'six', 'seven', 'eight' ],
[ 'nine', 'ten' ],
);

16. Declare function listify
sub listify {
my ($aref,$cc) = @_;
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
my $j;
for(my $i=0; $i<=$#$aref; $i+=$cc) {
push @$j, [@$aref[$i..$i+$cc-1]];
}
$#{$j->[$#{$j}]}=$#$aref%$cc;
@$aref = @$j;
return 1;
}
return;
}
sub listify {
}

17. Get Parameters
sub listify {
my ($aref,$cc) = @_;
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
my $j;
for(my $i=0; $i<=$#$aref; $i+=$cc) {
push @$j, [@$aref[$i..$i+$cc-1]];
}
$#{$j->[$#{$j}]}=$#$aref%$cc;
@$aref = @$j;
return 1;
}
return;
}
my ($aref,$cc) = @_;

18. Validate Parameters
sub listify {
my ($aref,$cc) = @_;
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
my $j;
for(my $i=0; $i<=$#$aref; $i+=$cc) {
push @$j, [@$aref[$i..$i+$cc-1]];
}
$#{$j->[$#{$j}]}=$#$aref%$cc;
@$aref = @$j;
return 1;
}
return;
}
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
}
return;

19. Declare Return Variable
sub listify {
my ($aref,$cc) = @_;
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
my $j;
for(my $i=0; $i<=$#$aref; $i+=$cc) {
push @$j, [@$aref[$i..$i+$cc-1]];
}
$#{$j->[$#{$j}]}=$#$aref%$cc;
@$aref = @$j;
return 1;
}
return;
}
my $j;

20. Loop Through Input Array
sub listify {
my ($aref,$cc) = @_;
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
my $j;
for(my $i=0; $i<=$#$aref; $i+=$cc) {
push @$j, [@$aref[$i..$i+$cc-1]];
}
$#{$j->[$#{$j}]}=$#$aref%$cc;
@$aref = @$j;
return 1;
}
return;
}
for(my $i=0; $i<=$#$aref; $i+=$cc) {
}

21. Add List to Output Variable
sub listify {
my ($aref,$cc) = @_;
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
my $j;
for(my $i=0; $i<=$#$aref; $i+=$cc) {
push @$j, [@$aref[$i..$i+$cc-1]];
}
$#{$j->[$#{$j}]}=$#$aref%$cc;
@$aref = @$j;
return 1;
}
return;
}
push @$j, [@$aref[$i..$i+$cc-1]];

22. ???
sub listify {
my ($aref,$cc) = @_;
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
my $j;
for(my $i=0; $i<=$#$aref; $i+=$cc) {
push @$j, [@$aref[$i..$i+$cc-1]];
}
$#{$j->[$#{$j}]}=$#$aref%$cc;
@$aref = @$j;
return 1;
}
return;
}
$#{$j->[$#{$j}]}=$#$aref%$cc;

23. Update Input Array In Place
sub listify {
my ($aref,$cc) = @_;
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
my $j;
for(my $i=0; $i<=$#$aref; $i+=$cc) {
push @$j, [@$aref[$i..$i+$cc-1]];
}
$#{$j->[$#{$j}]}=$#$aref%$cc;
@$aref = @$j;
return 1;
}
return;
}
@$aref = @$j;

24. Return 1 to Indicate Success
sub listify {
my ($aref,$cc) = @_;
if( ref $aref eq 'ARRAY' && $cc > 0 ) {
my $j;
for(my $i=0; $i<=$#$aref; $i+=$cc) {
push @$j, [@$aref[$i..$i+$cc-1]];
}
$#{$j->[$#{$j}]}=$#$aref%$cc;
@$aref = @$j;
return 1;
}
return;
}
return 1;

25. Clever (but not easy to read) Line
$#{$j->[$#{$j}]}=$#$aref%$cc;

26. Purpose of Clever Line
The purpose of the line is to truncate the final array to the number of remaining
elements so we don't end up with this:
@array = (
[ 'one', 'two', 'three', 'four' ],
[ 'five', 'six', 'seven', 'eight' ],
[ 'nine', 'ten', undef, undef ],
);

27. Improvement #1: Whitespace

28. Improvement #2: Refactor
$#{ $j->[ -1 ] } = $#$aref % $cc;
$#{ $j->[ $#{$j} ] } = $#$aref % $cc;

29. Improvement #3: Naming
$#{ $result_array[ -1 ] } = $#$in_aref % $elements_per_array;

30. Improvement #4: Multiple Lines
$final_aref = $result_array[ -1 ];
$#$final_aref = $#$in_aref % $elements_per_array;

31. Improvement #5: Split Another Line
my $final_aref = $result_array[ -1 ];
my $elements_in_final = $#$in_aref % $elements_per_array;
$#$final_aref = $elements_in_final;

32. Improvement #6: More Whitespace
my $final_aref = $result_array[ -1 ];
my $elements_in_final = $#$in_aref % $elements_per_array;
$#$final_aref = $elements_in_final;

33. Improvement #7: A comment!
my $final_aref = $result_array[ -1 ];
my $elements_in_final = $#$in_aref % $elements_per_array;
# Truncate final array
$#$final_aref = $elements_in_final;

34. Easier to Read Now?
Original:
$#{$j->[$#{$j}]}=$#$aref%$cc;
Revised:
my $final_aref = $result_array[ -1 ];
my $elements_in_final = $#$in_aref % $elements_per_array;
# Truncate final array
$#$final_aref = $elements_in_final;

35. Apply Principles to Entire Function
sub listify {
my ( $in_aref, $elements_per_array ) = @_;
return if (
ref $in_aref ne 'ARRAY' or
$elements_per_array <= 0
);
my @result_array;
for( my $i = 0; $i <= $#$in_aref; $i += $elements_per_array ) {
push @result_array, [
@$in_aref[ $i..$i + $elements_per_array - 1 ]
];
}
# Continued on next slide

36. Apply Principles to Entire Function
# Continued from previous slide
my $final_aref = $result_array[ -1 ];
my $elements_in_final = $#$in_aref % $elements_per_array;
# Truncate final array
$#$final_aref = $elements_in_final;
@$in_aref = @result_array;
}

37. Helpful Modules
Perl::Critic
based on the book “Perl Best Practices” by Damian
Conway
Perl::Tidy
increase readability of code

38. perlcritic Result
$ perlcritic -1 listify.pl
Code not contained in explicit package at line 1, column 1. Violates
encapsulation. (Severity: 4)
Code before strictures are enabled at line 1, column 1. See page
429 of PBP. (Severity: 5)
Subroutine "listify" does not end with "return" at line 1, column 1.
See page 197 of PBP. (Severity: 4)
Code before warnings are enabled at line 1, column 1. See page 431 of
PBP. (Severity: 4)
No package-scoped "$VERSION" variable found at line 1, column 1. See
page 404 of PBP. (Severity: 2)
C-style "for" loop used at line 10, column 7. See page 100 of PBP.
(Severity: 2)
Double-sigil dereference at line 10, column 26. See page 228 of PBP.
(Severity: 2)
(more double-sigil warnings follow)

39. Critical Fixes
Code not contained in explicit package at line 1, column 1. Violates
encapsulation. (Severity: 4)
Code before strictures are enabled at line 1, column 1. See page 429
of PBP. (Severity: 5)
Code before warnings are enabled at line 1, column 1. See page 431
of PBP. (Severity: 4)
sub listify {
my ( $in_aref, $elements_per_array ) = @_;
# --- cut ---
#!/usr/bin/perl
use strict;
use warnings;

40. Explicit Return
Subroutine "listify" does not end with "return" at line 2,
column 1. See page 197 of PBP. (Severity: 4)
# Truncate final array
$#$final_aref = $elements_in_final;
@$in_aref = @result_array;
}
return;

41. $VERSION
No package-scoped "$VERSION" variable found at line 1,
column 1. See page 404 of PBP. (Severity: 2)
#!/usr/bin/perl
use strict;
use warnings;
sub listify {
my ( $in_aref, $elements_per_array ) = @_;
# --- cut ---
our $VERSION = '1.19';

42. C-style "for" Loop
C-style "for" loop used at line 11, column 7. See page 100
of PBP. (Severity: 2)

43. C-style "for" Loop
C-style "for" loop used at line 11, column 7. See page 100
of PBP. (Severity: 2)
● “What?” No C-style “for” loops

44. C-style "for" Loop
C-style "for" loop used at line 11, column 7. See page 100
of PBP. (Severity: 2)
● “What?” No C-style “for” loops
● “Why?” More difficult to read and maintain

45. C-style "for" Loop
C-style "for" loop used at line 11, column 7. See page 100
of PBP. (Severity: 2)
● “What?” No C-style “for” loops
● “Why?” More difficult to read and maintain
● “I disagree.” That's OK. Modify Perl::Critic settings!

46. C-style "for" Loop
C-style "for" loop used at line 11, column 7. See page 100
of PBP. (Severity: 2)
● “What?” No C-style “for” loops
● “Why?” More difficult to read and maintain
● “I disagree.” That's OK. Modify Perl::Critic settings!
But today, I'm going to fix all the defaults

47. Change to “while” loop
C-style "for" loop used at line 11, column 7. See page 100 of
PBP. (Severity: 2)
Old:
for( my $i = 0; $i <= $#$in_aref; $i += $elements_per_array ) {
# (loop contents)
}
New:
my $i = 0;
while($i <= $#$in_aref) {
# (loop contents)
$i += $elements_per_array;
}

48. Double-sigil dereference
● Caused by
– @$my_array_reference
● Fixed with
– @{ $my_array_reference }

49. JAPH: The Do-Not Example
sub q{ord($_[0])}sub qq{chr($_[0])}(@q=(j,q,q,,q,s,,u,o,[$;=@q,$"=sub{for(@q){
s/(.)/&qq(&q($1)-1)/e}},$_=q,*534`!./4(%2`0%2{`(!#+%2,,tr;{;,;,s/(.)/&q($1)>95?
&qq(&q($1)-64):&qq(&q($ 1)+64)/eg,% q=(q,qq,,sub{eval$ _[0]},q,q,,1)])),&{$ "},
$q{qq}->(qq.$;->[$q=$q{q}]${$;}[++$q]$;->[$[]${$;}[-1+$)-$ )+$#q]$;->[$#q-$q].)

50. JAPH: The Do-Not Example
sub q{ord($_[0])}sub qq{chr($_[0])}(@q=(j,q,q,,q,s,,u,o,[$;=@q,$"=sub{for(@q){
s/(.)/&qq(&q($1)-1)/e}},$_=q,*534`!./4(%2`0%2{`(!#+%2,,tr;{;,;,s/(.)/&q($1)>95?
&qq(&q($1)-64):&qq(&q($ 1)+64)/eg,% q=(q,qq,,sub{eval$ _[0]},q,q,,1)])),&{$ "},
$q{qq}->(qq.$;->[$q=$q{q}]${$;}[++$q]$;->[$[]${$;}[-1+$)-$ )+$#q]$;->[$#q-$q].)
● Ugly variables $" $; $ " and even $_, @_

51. JAPH: The Do-Not Example
sub q{ord($_[0])}sub qq{chr($_[0])}(@q=(j,q,q,,q,s,,u,o,[$;=@q,$"=sub{for(@q){
s/(.)/&qq(&q($1)-1)/e}},$_=q,*534`!./4(%2`0%2{`(!#+%2,,tr;{;,;,s/(.)/&q($1)>95?
&qq(&q($1)-64):&qq(&q($ 1)+64)/eg,% q=(q,qq,,sub{eval$ _[0]},q,q,,1)])),&{$ "},
$q{qq}->(qq.$;->[$q=$q{q}]${$;}[++$q]$;->[$[]${$;}[-1+$)-$ )+$#q]$;->[$#q-$q].)
● Ugly variables $" $; $ " and even $_, @_
– use English;

52. JAPH: The Do-Not Example
sub q{ord($_[0])}sub qq{chr($_[0])}(@q=(j,q,q,,q,s,,u,o,[$;=@q,$"=sub{for(@q){
s/(.)/&qq(&q($1)-1)/e}},$_=q,*534`!./4(%2`0%2{`(!#+%2,,tr;{;,;,s/(.)/&q($1)>95?
&qq(&q($1)-64):&qq(&q($ 1)+64)/eg,% q=(q,qq,,sub{eval$ _[0]},q,q,,1)])),&{$ "},
$q{qq}->(qq.$;->[$q=$q{q}]${$;}[++$q]$;->[$[]${$;}[-1+$)-$ )+$#q]$;->[$#q-$q].)
● Ugly variables $" $; $ " and even $_, @_
– use English;
● 74% non-alpha/space

53. JAPH: The Do-Not Example
sub q{ord($_[0])}sub qq{chr($_[0])}(@q=(j,q,q,,q,s,,u,o,[$;=@q,$"=sub{for(@q){
s/(.)/&qq(&q($1)-1)/e}},$_=q,*534`!./4(%2`0%2{`(!#+%2,,tr;{;,;,s/(.)/&q($1)>95?
&qq(&q($1)-64):&qq(&q($ 1)+64)/eg,% q=(q,qq,,sub{eval$ _[0]},q,q,,1)])),&{$ "},
$q{qq}->(qq.$;->[$q=$q{q}]${$;}[++$q]$;->[$[]${$;}[-1+$)-$ )+$#q]$;->[$#q-$q].)
● Ugly variables $" $; $ " and even $_, @_
– use English;
● 74% non-alpha/space
– More non-alpha characters, more difficult to read

54. Other Considerations
● Conformity can be good

55. Other Considerations
● Conformity can be good
● How to implement good change?

56. Other Considerations
● Conformity can be good
● How to implement good change?
● The “next guy” might be YOU.

57. Other Considerations
● Conformity can be good
● How to implement good change?
● The “next guy” might be YOU.
● Comment to preempt disputes or misunderstandings

58. Best Book on this Topic
Perl Best Practices by Damian Conway

59. Questions?

60. Thank You!
David Bradford
@tinypig
tinypig.com
Web Engineer at OmniTI
omniti.com/presents