No need to have a perl style if we've not got perl.
This commit is contained in:
Josef Karthauser
parent
185bb48343
commit
1e4dc2da26
@ -1,246 +0,0 @@
|
||||
.\" 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 .
|
||||
Loading…
Reference in New Issue
Block a user