1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
$OpenBSD: OpenBSD::style.pod,v 1.1 2020/01/04 13:48:49 schwarze Exp $
=head1 NAME
OpenBSD::style - Perl source file style guide
=head1 DESCRIPTION
This file specifies the preferred style for Perl source files
in the OpenBSD source tree.
The suggestions in L<style(9)> also apply as far as they make sense
for Perl code and unless they are overridden in the present manual page.
Just as for L<style(9)>, indentation is an 8 character tab,
and statements continuing on the next line are indented
by four more spaces.
=head2 Subroutines and methods
Prefer object-oriented over procedural style for new code.
Define a package under either C<OpenBSD::> or C<DPB::>.
If no state variables are needed, call methods directly on the class name.
Otherwise, define the state variables as member variables
and call methods on a constructed object.
Name the constructor new() unless there are better options.
my $pkgpath = DPB::PkgPath->new('devel/quirks');
say "Normalized version is ", $pkgpath->fullpkgpath;
$state->errsay(OpenBSD::Temp->last_error);
Inside methods, call the object C<$self> unless there are reasons not to.
For functions with multiple parameters,
use list assignment to retrieve the arguments:
sub m3
{
my ($self, $p1, $p2) = @_;
...
}
Usually, there is no need to check the number of arguments.
For functions with exactly one parameter, one can alternatively
retrieve the argument with the shift() function:
sub width
{
my $self = shift;
...
}
Because it takes no argument apart from the object itself, calling
such a method doesn't need trailing empty parentheses:
my $columns = $object->width;
If a function passes on an arbitrary number of arguments
to another function:
sub wrapper_method
{
my $self = shift;
...
do_something_with(@_);
}
Mark the last expression at the end of a function with an explicit
B<return> unless the function is is not intended to return anything.
Avoid using the wantarray() function except as an optimzation;
it should not change the semantics of the subroutine.
Let methods that tweak an object return the object itself,
such that methods can be chained:
$object->polish->paint('blue')->attach(@decorations);
Since there are no access control restrictions in Perl,
simply mark internal methods by prefixing their names with C<_>.
Treat anonymous subroutines just like other code,
indenting them by one tab:
my $s = sub {
my $self = shift;
...
};
When passing an anonymous function as an argument, start it on a new line:
f($a1, $a2,
sub {
my $self = shift;
...
});
=head2 Files and packages
Putting several closely related classes
into the same source file is fine.
Avoid multiple inheritance unless absolutely necessary
because it almost always turns into a mess.
Including some behavior from a different class (mixin)
is best done on a per-method basis.
Delegating from one method of one class to a method of another class,
passing C<@_> completely unchanged, can be done with the following syntax:
package Borrower;
sub visit_notary
{
&Lender::visit_notary; # no parentheses here
}
=head2 Data structures
Autovivification is welcome:
push @{$self->{list}}, $value;
is fine without defining C<$self-E<gt>{list}> first.
Note that
if (@{$self->{list}} > 0)
will not autovivify C<$self-E<gt>{list}>,
so it can be used to check that the list exists and is not empty
without testing C<if (exists $self-E<gt>{list})> first.
Don't put quotes around hash subscripts unless necessary;
they are not necessary for simple identifiers that are not keywords.
Avoid using keywords as hash keys.
Avoid needless arrows in chained lookups.
Rather than C<$self-E<gt>{a}-E<gt>{b}>, write:
$self->{a}{b}
=head2 Syntax details
This style guide makes no recommendation to put parentheses
where they are not required.
For example, calling built-in or prototyped functions
does not require parentheses.
Modern Perl operators are preferred.
Rather than C<defined $value or $value = $something;>
or C<$value = $something unless defined $value;>, write:
$value //= $something;
|
