summaryrefslogtreecommitdiff
path: root/usr.sbin
diff options
context:
space:
mode:
Diffstat (limited to 'usr.sbin')
-rw-r--r--usr.sbin/pkg_add/OpenBSD/style.pod90
1 files changed, 64 insertions, 26 deletions
diff --git a/usr.sbin/pkg_add/OpenBSD/style.pod b/usr.sbin/pkg_add/OpenBSD/style.pod
index 58f2f612439..96c262fefd9 100644
--- a/usr.sbin/pkg_add/OpenBSD/style.pod
+++ b/usr.sbin/pkg_add/OpenBSD/style.pod
@@ -1,4 +1,4 @@
-$OpenBSD: style.pod,v 1.1 2020/12/20 15:30:58 daniel Exp $
+$OpenBSD: style.pod,v 1.2 2023/05/18 16:30:01 espie Exp $
=head1 NAME
@@ -16,6 +16,9 @@ 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.
+Systematically C<use v5.36> or later which yields C<strict>, C<warnings>,
+C<say> and function signatures.
+
=head2 Subroutines and methods
Prefer object-oriented over procedural style for new code.
@@ -32,46 +35,78 @@ Name the constructor new() unless there are better options.
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:
+Use signatures for every function (except delegations), so that the number
+of parameters can be checked.
- sub m3
+ sub m3($self, $p1, $p2)
{
- my ($self, $p1, $p2) = @_;
...
}
-Usually, there is no need to check the number of arguments.
+Accordingly, avoid calling code refs without parentheses, since this creates
+an implicit C<@_> reference.
-For functions with exactly one parameter, one can alternatively
-retrieve the argument with the shift() function:
+Note that signatures can also absorb an arbitrary number of parameters with
+C<@l> and set default parameter values like in C++, e.g.
- sub width
- {
- my $self = shift;
- ...
- }
+ sub do_backsubst($subst, $string, $unsubst = undef,
+ $context = 'OpenBSD::PackingElement');
-Because it takes no argument apart from the object itself, calling
-such a method doesn't need trailing empty parentheses:
+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
+ sub wrapper_method($self, @p)
{
- my $self = shift;
...
- do_something_with(@_);
+ 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 C<__DIE__> and C<__WARN__>.
+
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.
+B<return> unless the function is is not intended to return anything,
+or for "constant" methods
+
+ sub isFile($)
+ {
+ 1;
+ }
-Avoid using the wantarray() function except as an optimization;
-it should not change the semantics of the subroutine.
+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 wantarray() 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.
@@ -102,16 +137,14 @@ 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;
+ my $s = sub($self) {
...
};
When passing an anonymous function as an argument, start it on a new line:
f($a1, $a2,
- sub {
- my $self = shift;
+ sub($self) {
...
});
@@ -123,7 +156,9 @@ 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.
+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 C<@_> completely unchanged, can be done with the following syntax:
@@ -134,6 +169,9 @@ passing C<@_> completely unchanged, can be done with the following syntax:
&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 fork(), set
$DB::inhibit_exit = 0;