share/man/man7/style.perl.7

   1 .\" Copyright (c) 2000 Josef Karthauser <joe@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/share/man/man7/style.perl.7,v 1.12.2.3 2001/08/17 13:08:49 ru Exp $
  26 .\"
  27 .Dd October 16, 2000
  28 .Dt STYLE.PERL 7
  29 .Os
  30 .Sh NAME
  31 .Nm style.perl
  32 .Nd "FreeBSD Perl source file style guide"
  33 .Sh DESCRIPTION
  34 This file specifies the preferred style for perl scripts in the
  35 .Fx
  36 source tree.
  37 .Bd -literal
  38 #
  39 # Style guide for Perl.  Based on the kernel style guide.
  40 #
  41
  42 #
  43 # VERY important single-line comments look like this.
  44 #
  45
  46 # Most single-line comments look like this.
  47
  48 # Multi-line comments look like this.  Make them real sentences.
  49 # Fill them so they look like real paragraphs.
  50 .Ed
  51 .Pp
  52 All scripts should follow the copyright block at the start of the
  53 script with a comment block that describes what the script does.
  54 .Bd -literal
  55 #!/usr/bin/perl -w
  56
  57 # COPYRIGHT
  58 # BLOCK
  59
  60 # This script processes an old kernel config file, which it gets on
  61 # stdin, and outputs a new style hints file to stdout.
  62 .Ed
  63 .Pp
  64 All scripts should use the
  65 .Xr strict 3
  66 module and run without warnings.
  67 For example:
  68 .Bd -literal
  69 #!/usr/bin/perl -w
  70
  71 # Copyright, description of what the script does, etc
  72
  73 use strict;
  74 \&...
  75 .Ed
  76 .Pp
  77 Where possible run the script with taint mode switched on.
  78 This is documented in
  79 .Xr perlsec 1 .
  80 .Bd -literal
  81 #!/usr/bin/perl -wT
  82 .Ed
  83 .Pp
  84 The main program should be placed in a block labeled MAIN:.
  85 This
  86 makes it easier to identify the entry point in a large perl script,
  87 and provides a scope for variables which are used in the main
  88 program but nowhere else.
  89 .Bd -literal
  90 MAIN:{
  91         print(foo("/usr/bin/man", "7", "style.perl"));
  92         exit(0);
  93 }
  94 .Ed
  95 .Pp
  96 All subroutines should be defined using argument prototypes as defined in
  97 .Xr perlsub 1 .
  98 .Bd -literal
  99 sub foo($@) {
 100         my $cmd = shift;
 101         my @args = @_;
 102 }
 103 .Ed
 104 .Pp
 105 All variables should be defined before use; this is enforced if operating
 106 under
 107 .Ic use Ar strict .
 108 .Pp
 109 Scope local variables should be defined using
 110 .Ic my
 111 .Va $variable
 112 and not
 113 .Ic local
 114 .Va $variable .
 115 The
 116 .Ic local
 117 declaration should only be used when it is required, and not by
 118 default.
 119 Lots of perl4 scripts use
 120 .Ic local
 121 because the
 122 .Ic my
 123 definition didn't exist prior to perl5.
 124 .Pp
 125 In most cases globals should be defined at the top of the code
 126 using a
 127 .Xr vars 3
 128 definition block:
 129 .Bd -literal
 130 use vars qw($globalscalar @globalarray %globalhash);
 131 .Ed
 132 .Pp
 133 In some cases it may be appropriate to use
 134 .Ic my
 135 statements at the top of the script as an alternative to using
 136 .Xr vars 3
 137 declarations.
 138 .Pp
 139 All variables should be commented.
 140 .Bd -literal
 141 sub foo($@) {
 142         my $cmd = shift;        # Command to run
 143         my @args = @_;          # Arguments to $cmd
 144 }
 145 .Ed
 146 .Pp
 147 Local variables should be separated from function arguments by a
 148 blank line:
 149 .Bd -literal
 150 sub foo($@) {
 151         my $cmd = shift;        # Command to run
 152         my @args = @_;          # Arguments to command
 153
 154         my $pid;                # Child PID
 155         local *PIPE;            # Pipe
 156         my $output;             # Output from command
 157 }
 158 .Ed
 159 .Pp
 160 Whenever possible code should be run through the code checker
 161 .Nm perl
 162 .Fl wc
 163 .Ar script.pl
 164 or
 165 .Nm perl
 166 .Fl wcT
 167 .Ar script.pl
 168 and produce no warnings.
 169 .Pp
 170 Indentation is an 8 character tab.
 171 Second level indents are four spaces.
 172 .Bd -literal
 173 while (cnt < 20) {
 174         z = a + really + long + statement + that + needs +
 175             two lines + gets + indented + four + spaces +
 176             on + the + second + and + subsequent + lines.
 177 }
 178 .Ed
 179 .Pp
 180 Do not add whitespace at the end of a line, and only use tabs
 181 followed by spaces to form the indentation.
 182 Do not use more spaces
 183 than a tab will produce and do not use spaces in front of tabs.
 184 .Pp
 185 Opening braces should be at the end of the controlling line.
 186 Else
 187 and elsif belong on the same line as the closing brace for the
 188 previous if or elsif block:
 189 .Bd -literal
 190 sub foo($@) {
 191         my $cmd = shift;            # Command to run
 192         my @args = @_;              # Arguments to command
 193
 194         my $pid;                    # Child PID
 195         local *PIPE;                # Pipe
 196         my $output;                 # Output from command
 197
 198         unless (defined($pid = open(PIPE, "-|"))) {
 199                 die("open(): $!\\n");
 200         } elsif ($pid == 0) {
 201                 exec($cmd, @args);
 202                 die("exec(): $!\\n");
 203         }
 204         $output = "";
 205         while (<PIPE>) {
 206                 $output .= $_;
 207         }
 208         waitpid($pid, 0);
 209         if ($? & 0xff) {
 210                 die("$cmd caught a signal " . ($? & 0x7f) . "\\n");
 211         } elsif ($?) {
 212                 die("$cmd returned exit code " . ($? >> 8) . "\\n");
 213         }
 214         return $output;
 215 }
 216 .Ed
 217 .Pp
 218 Where possible scripts should use standard modules instead of
 219 rewriting the code inline.
 220 It may be appropriate in some cases to
 221 import a CPAN module into the base system to facilitate this.
 222 .Pp
 223 Use
 224 .Ic chomp
 225 instead of
 226 .Ic chop
 227 where appropriate.
 228 .Pp
 229 Use
 230 .Ic unless
 231 instead of
 232 .Ic if Pq Cm \&! No ...\&
 233 where it improves readability.
 234 .Pp
 235 Where it doesn't conflict with this guide read
 236 .Xr perlstyle 1
 237 and adopt Larry Wall's style recommendations.
 238 .Sh SEE ALSO
 239 .Xr perlsec 1 ,
 240 .Xr perlstyle 1 ,
 241 .Xr style 9
 242 .Sh HISTORY
 243 This man page is largely based on the
 244 .Xr style 9
 245 man page in
 246 .Fx .