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