OpenBSD::style(3p) Perl Programmers Reference Guide OpenBSD::style(3p)

OpenBSD::style(3p) Perl Programmers Reference Guide OpenBSD::style(3p) #

OpenBSD::style(3p) Perl Programmers Reference Guide OpenBSD::style(3p)

NNAAMMEE #

 OpenBSD::style - Perl source file style guide

DDEESSCCRRIIPPTTIIOONN #

 This file specifies the preferred style for Perl source files in the
 OpenBSD source tree.

 The suggestions in ssttyyllee(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 ssttyyllee(9), indentation is an 8 character tab, and statements
 continuing on the next line are indented by four more spaces.

 Systematically "use v5.36" or later which yields "strict", "warnings",
 "say" and function signatures.

SSuubbrroouuttiinneess aanndd mmeetthhooddss Prefer object-oriented over procedural style for new code. Define a package under either “OpenBSD::” or “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 nneeww(()) 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 $self unless there are reasons not to.

 Use signatures for every function (except delegations), so that the
 number of parameters can be checked.

         sub m3($self, $p1, $p2)
         {
                 ...
         }

 Accordingly, avoid calling code refs without parentheses, since this
 creates an implicit @_ reference.

 Note that signatures can also absorb an arbitrary number of parameters
 with @l and set default parameter values like in C++, e.g.

         sub do_backsubst($subst, $string, $unsubst = undef,
             $context = 'OpenBSD::PackingElement');

 For methods that take no argument apart from the object itself, remove
 trailing parentheses for the method call:

         my $columns = $object->width;

 If a function passes on an arbitrary number of arguments to another
 function:

         sub wrapper_method($self, @p)
         {
                 ...
                 do_something_with(@p);
         }

 Anonymous subs should also use signatures

         $state->{opt}{x} =
             sub($opt) {
                 push ${$state->{xlist}}, $opt);
             };

 (Exception: signal handlers are currently not specified and may take an
 arbitrary number of parameters for "__DIE__" and "__WARN__".

 Mark the last expression at the end of a function with an explicit rreettuurrnn
 unless the function is not intended to return anything, or for "constant"
 methods

         sub isFile($)
         {
                 1;
         }

 Do not name parameters to methods unless actually used.  For
 documentation, use a comment in that case (especially useful for base
 methods)

         # $self->foo($state):
         #       explain what foo does
         sub foo($, $)
         {
         }

 Avoid using old-style function prototypes unless absolutely necessary to
 create syntax:

         sub try :prototype(&@)
         {
                 my ($try, $catch) = @_;
                 eval { &$try() };
                 dienow($@, $catch);
         }

 Only use the wwaannttaarrrraayy(()) built-in as an optimization; it should never
 change the semantics of the subroutine.  For example, suppose there is a
 function returning a list, and while the question whether the list is
 empty sometimes needs to be asked, the number of elements never matters.
 Such a function can be structured and used as follows:

         sub get_list
         {
                 if (wantarray) {
                         # build the complete list and return it
                 } else {
                         # only figure out whether the list is empty
                         # and return 0 if it is or 1 otherwise
                 }
         }

         if (get_list) {
                 # do something that doesn't need the actual elements
         }

 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 "_".

 Treat anonymous subroutines just like other code, indenting them by one
 tab:

         my $s = sub($self) {
                 ...
                 };

 When passing an anonymous function as an argument, start it on a new
 line:

         f($a1, $a2,
             sub($self) {
                 ...
                 });

FFiilleess aanndd ppaacckkaaggeess 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, but explicitly annotate the
 mixins as such.

 Delegating from one method of one class to a method of another class,
 passing @_ completely unchanged, can be done with the following syntax:

         package Borrower;

         sub visit_notary
         {
                 &Lender::visit_notary;  # no parentheses here
         }

 This is the only case where a code ref should be called without explicit
 parameters, and where a method can be declared without a prototype.

 If a program often uses ffoorrkk(()), set

         $DB::inhibit_exit = 0;

 right after each ffoorrkk(()) and before the following eexxeecc(()), such that a user
 trying to debug the main program isn't prompted each time one of the
 child processes exits.

DDaattaa ssttrruuccttuurreess Autovivification is welcome:

         push @{$self->{list}}, $value;

 is fine without defining "$self->{list}" first.  Note that

         if (@{$self->{list}} > 0)

 will not autovivify "$self->{list}", so it can be used to check that the
 list exists and is not empty without testing "if (exists $self->{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 "$self->{a}->{b}",
 write:

         $self->{a}{b}

SSyynnttaaxx ddeettaaiillss 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 "defined $value or
 $value = $something;" or "$value = $something unless defined $value;",
 write:

         $value //= $something;

perl v5.36.3 2023-09-14 OpenBSD::style(3p)