247 lines
6.0 KiB
Groff
247 lines
6.0 KiB
Groff
.\" Copyright (c) 2000 Josef Karthauser <joe@FreeBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd October 16, 2000
|
|
.Dt STYLE.PERL 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm style.perl
|
|
.Nd "FreeBSD Perl source file style guide"
|
|
.Sh DESCRIPTION
|
|
This file specifies the preferred style for perl scripts in the
|
|
.Fx
|
|
source tree.
|
|
.Bd -literal
|
|
#
|
|
# Style guide for Perl. Based on the kernel style guide.
|
|
#
|
|
|
|
#
|
|
# VERY important single-line comments look like this.
|
|
#
|
|
|
|
# Most single-line comments look like this.
|
|
|
|
# Multi-line comments look like this. Make them real sentences.
|
|
# Fill them so they look like real paragraphs.
|
|
.Ed
|
|
.Pp
|
|
All scripts should follow the copyright block at the start of the
|
|
script with a comment block that describes what the script does.
|
|
.Bd -literal
|
|
#!/usr/bin/perl -w
|
|
|
|
# COPYRIGHT
|
|
# BLOCK
|
|
|
|
# This script processes an old kernel config file, which it gets on
|
|
# stdin, and outputs a new style hints file to stdout.
|
|
.Ed
|
|
.Pp
|
|
All scripts should use the
|
|
.Xr strict 3
|
|
module and run without warnings.
|
|
For example:
|
|
.Bd -literal
|
|
#!/usr/bin/perl -w
|
|
|
|
# Copyright, description of what the script does, etc
|
|
|
|
use strict;
|
|
\&...
|
|
.Ed
|
|
.Pp
|
|
Where possible run the script with taint mode switched on.
|
|
This is documented in
|
|
.Xr perlsec 1 .
|
|
.Bd -literal
|
|
#!/usr/bin/perl -wT
|
|
.Ed
|
|
.Pp
|
|
The main program should be placed in a block labeled MAIN:.
|
|
This
|
|
makes it easier to identify the entry point in a large perl script,
|
|
and provides a scope for variables which are used in the main
|
|
program but nowhere else.
|
|
.Bd -literal
|
|
MAIN:{
|
|
print(foo("/usr/bin/man", "7", "style.perl"));
|
|
exit(0);
|
|
}
|
|
.Ed
|
|
.Pp
|
|
All subroutines should be defined using argument prototypes as defined in
|
|
.Xr perlsub 1 .
|
|
.Bd -literal
|
|
sub foo($@) {
|
|
my $cmd = shift;
|
|
my @args = @_;
|
|
}
|
|
.Ed
|
|
.Pp
|
|
All variables should be defined before use; this is enforced if operating
|
|
under
|
|
.Ic use Ar strict .
|
|
.Pp
|
|
Scope local variables should be defined using
|
|
.Ic my
|
|
.Va $variable
|
|
and not
|
|
.Ic local
|
|
.Va $variable .
|
|
The
|
|
.Ic local
|
|
declaration should only be used when it is required, and not by
|
|
default.
|
|
Lots of perl4 scripts use
|
|
.Ic local
|
|
because the
|
|
.Ic my
|
|
definition didn't exist prior to perl5.
|
|
.Pp
|
|
In most cases globals should be defined at the top of the code
|
|
using a
|
|
.Xr vars 3
|
|
definition block:
|
|
.Bd -literal
|
|
use vars qw($globalscalar @globalarray %globalhash);
|
|
.Ed
|
|
.Pp
|
|
In some cases it may be appropriate to use
|
|
.Ic my
|
|
statements at the top of the script as an alternative to using
|
|
.Xr vars 3
|
|
declarations.
|
|
.Pp
|
|
All variables should be commented.
|
|
.Bd -literal
|
|
sub foo($@) {
|
|
my $cmd = shift; # Command to run
|
|
my @args = @_; # Arguments to $cmd
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Local variables should be separated from function arguments by a
|
|
blank line:
|
|
.Bd -literal
|
|
sub foo($@) {
|
|
my $cmd = shift; # Command to run
|
|
my @args = @_; # Arguments to command
|
|
|
|
my $pid; # Child PID
|
|
local *PIPE; # Pipe
|
|
my $output; # Output from command
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Whenever possible code should be run through the code checker
|
|
.Nm perl
|
|
.Fl wc
|
|
.Ar script.pl
|
|
or
|
|
.Nm perl
|
|
.Fl wcT
|
|
.Ar script.pl
|
|
and produce no warnings.
|
|
.Pp
|
|
Indentation is an 8 character tab.
|
|
Second level indents are four spaces.
|
|
.Bd -literal
|
|
while (cnt < 20) {
|
|
z = a + really + long + statement + that + needs +
|
|
two lines + gets + indented + four + spaces +
|
|
on + the + second + and + subsequent + lines.
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Do not add whitespace at the end of a line, and only use tabs
|
|
followed by spaces to form the indentation.
|
|
Do not use more spaces
|
|
than a tab will produce and do not use spaces in front of tabs.
|
|
.Pp
|
|
Opening braces should be at the end of the controlling line.
|
|
Else
|
|
and elsif belong on the same line as the closing brace for the
|
|
previous if or elsif block:
|
|
.Bd -literal
|
|
sub foo($@) {
|
|
my $cmd = shift; # Command to run
|
|
my @args = @_; # Arguments to command
|
|
|
|
my $pid; # Child PID
|
|
local *PIPE; # Pipe
|
|
my $output; # Output from command
|
|
|
|
unless (defined($pid = open(PIPE, "-|"))) {
|
|
die("open(): $!\\n");
|
|
} elsif ($pid == 0) {
|
|
exec($cmd, @args);
|
|
die("exec(): $!\\n");
|
|
}
|
|
$output = "";
|
|
while (<PIPE>) {
|
|
$output .= $_;
|
|
}
|
|
waitpid($pid, 0);
|
|
if ($? & 0xff) {
|
|
die("$cmd caught a signal " . ($? & 0x7f) . "\\n");
|
|
} elsif ($?) {
|
|
die("$cmd returned exit code " . ($? >> 8) . "\\n");
|
|
}
|
|
return $output;
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Where possible scripts should use standard modules instead of
|
|
rewriting the code inline.
|
|
It may be appropriate in some cases to
|
|
import a CPAN module into the base system to facilitate this.
|
|
.Pp
|
|
Use
|
|
.Ic chomp
|
|
instead of
|
|
.Ic chop
|
|
where appropriate.
|
|
.Pp
|
|
Use
|
|
.Ic unless
|
|
instead of
|
|
.Ic if Pq Cm \&! No ...\&
|
|
where it improves readability.
|
|
.Pp
|
|
Where it doesn't conflict with this guide read
|
|
.Xr perlstyle 1
|
|
and adopt Larry Wall's style recommendations.
|
|
.Sh SEE ALSO
|
|
.Xr perlsec 1 ,
|
|
.Xr perlstyle 1 ,
|
|
.Xr style 9
|
|
.Sh HISTORY
|
|
This man page is largely based on the
|
|
.Xr style 9
|
|
man page in
|
|
.Fx .
|