1 .\" Copyright (c) 2000 Josef Karthauser <joe@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
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.2 2003/06/17 04:37:00 dillon Exp $
33 .Nd "FreeBSD Perl source file style guide"
35 This file specifies the preferred style for perl scripts in the
40 # Style guide for Perl. Based on the kernel style guide.
44 # VERY important single-line comments look like this.
47 # Most single-line comments look like this.
49 # Multi-line comments look like this. Make them real sentences.
50 # Fill them so they look like real paragraphs.
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.
61 # This script processes an old kernel config file, which it gets on
62 # stdin, and outputs a new style hints file to stdout.
65 All scripts should use the
67 module and run without warnings.
72 # Copyright, description of what the script does, etc
78 Where possible run the script with taint mode switched on.
85 The main program should be placed in a block labeled MAIN:.
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.
92 print(foo("/usr/bin/man", "7", "style.perl"));
97 All subroutines should be defined using argument prototypes as defined in
106 All variables should be defined before use; this is enforced if operating
110 Scope local variables should be defined using
118 declaration should only be used when it is required, and not by
120 Lots of perl4 scripts use
124 definition didn't exist prior to perl5.
126 In most cases globals should be defined at the top of the code
131 use vars qw($globalscalar @globalarray %globalhash);
134 In some cases it may be appropriate to use
136 statements at the top of the script as an alternative to using
140 All variables should be commented.
143 my $cmd = shift; # Command to run
144 my @args = @_; # Arguments to $cmd
148 Local variables should be separated from function arguments by a
152 my $cmd = shift; # Command to run
153 my @args = @_; # Arguments to command
157 my $output; # Output from command
161 Whenever possible code should be run through the code checker
169 and produce no warnings.
171 Indentation is an 8 character tab.
172 Second level indents are four spaces.
175 z = a + really + long + statement + that + needs +
176 two lines + gets + indented + four + spaces +
177 on + the + second + and + subsequent + lines.
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.
186 Opening braces should be at the end of the controlling line.
188 and elsif belong on the same line as the closing brace for the
189 previous if or elsif block:
192 my $cmd = shift; # Command to run
193 my @args = @_; # Arguments to command
197 my $output; # Output from command
199 unless (defined($pid = open(PIPE, "-|"))) {
200 die("open(): $!\\n");
201 } elsif ($pid == 0) {
203 die("exec(): $!\\n");
211 die("$cmd caught a signal " . ($? & 0x7f) . "\\n");
213 die("$cmd returned exit code " . ($? >> 8) . "\\n");
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.
233 .Ic if Pq Cm \&! No ...\&
234 where it improves readability.
236 Where it doesn't conflict with this guide read
238 and adopt Larry Wall's style recommendations.
244 This man page is largely based on the