Index: trunk/doc/misc/perlCodeConventions.tex =================================================================== --- trunk/doc/misc/perlCodeConventions.tex (revision 2377) +++ trunk/doc/misc/perlCodeConventions.tex (revision 2378) @@ -1,3 +1,3 @@ -%%% $Id: perlCodeConventions.tex,v 1.19 2004-11-16 22:15:07 jhoblitt Exp $ +%%% $Id: perlCodeConventions.tex,v 1.20 2004-11-16 23:40:04 jhoblitt Exp $ \documentclass[panstarrs]{panstarrs} @@ -56,8 +56,8 @@ \begin{verbatim} - Adapted with permission from - CODE CONVENTIONS FOR THE JAVA^TM PROGRAMMING LANGUAGE. - Copyright 1995-1999 Sun - Microsysytems, Inc. All rights reserved. + Adapted with permission from + CODE CONVENTIONS FOR THE JAVA^TM PROGRAMMING LANGUAGE. + Copyright 1995-1999 Sun + Microsysytems, Inc. All rights reserved. \end{verbatim} @@ -193,23 +193,23 @@ \normalsize \begin{verbatim} -use 5.008005; # optional - -use strict; # not optional -use warnings; # not optional - -use Foo qw( $bar ); # import $bar into our namespace - -use constant MAXFOO => 3; # maximum number of foos - -my $baz; # is a lexical variable in the top level scope - -sub fuu -{ - -} - -__END__ - -... + use 5.008005; # optional + + use strict; # not optional + use warnings; # not optional + + use Foo qw( $bar ); # import $bar into our namespace + + use constant MAXFOO => 3; # maximum number of foos + + my $baz; # is a lexical variable in the top level scope + + sub fuu + { + + } + + __END__ + + ... \end{verbatim} @@ -267,25 +267,25 @@ \normalsize \begin{verbatim} -package Foo; - -use 5.008005; # optional - -use strict; # not optional -use warnings; # not optional - -use base qw( Baz ); # become a subclass of Baz - -use Foo qw( $bar ); # import $bar into our namespace - -use constant MAXFOO => 3; # maximum number of foos - -my $baz; # is a lexical variable in the top level scope - -sub fuu -{ - -} - -1; + package Foo; + + use 5.008005; # optional + + use strict; # not optional + use warnings; # not optional + + use base qw( Baz ); # become a subclass of Baz + + use Foo qw( $bar ); # import $bar into our namespace + + use constant MAXFOO => 3; # maximum number of foos + + my $baz; # is a lexical variable in the top level scope + + sub fuu + { + + } + + 1; __END__ @@ -301,78 +301,78 @@ \begin{verbatim} -=pod - -=head1 NAME - -Foo - Does something with Baz. - -=head1 SYNOPSIS - - use Foo; + =pod + + =head1 NAME + + Foo - Does something with Baz. + + =head1 SYNOPSIS + + use Foo; + + ... + + =head1 DESCRIPTION + + More details about what this modules does with Baz. + + =head1 USAGE + + =head2 Import Parameters + + This module accepts no arguments to it's C method and exports no + I. + + =head2 Methods + + =head3 Class Methods + + =over 4 + + =item * methodOne + + details of methodOne + + =item * methodTwo + + details of methodTwo ... -=head1 DESCRIPTION - -More details about what this modules does with Baz. - -=head1 USAGE - -=head2 Import Parameters - -This module accepts no arguments to it's C method and exports no -I. - -=head2 Methods - -=head3 Class Methods - -=over 4 - -=item * methodOne - -details of methodOne - -=item * methodTwo - -details of methodTwo - -... - -=back - -=head1 SUPPORT - -Where to get help. - -=head1 AUTHOR - -Principle authors and contact info. - -=head1 COPYRIGHT - -Copyright (C) 2004 Robert Lupton. All rights reserved. - -This program is free software; you can redistribute it and/or modify it under -the terms of the GNU General Public License as published by the Free Software -Foundation; either version 2 of the License, or (at your option) any later -version. - -This program is distributed in the hope that it will be useful, but WITHOUT ANY -WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A -PARTICULAR PURPOSE. See the GNU General Public License for more details. - -You should have received a copy of the GNU General Public License along with -this program; if not, write to the Free Software Foundation, Inc., 59 Temple -Place - Suite 330, Boston, MA 02111-1307, USA. - -The full text of the license can be found in the LICENSE file included with -this module, or in the L Pod as supplied with Perl 5.8.1 and later. - -=head1 SEE ALSO - -L - -=cut + =back + + =head1 SUPPORT + + Where to get help. + + =head1 AUTHOR + + Principle authors and contact info. + + =head1 COPYRIGHT + + Copyright (C) 2004 Robert Lupton. All rights reserved. + + This program is free software; you can redistribute it and/or modify it under + the terms of the GNU General Public License as published by the Free Software + Foundation; either version 2 of the License, or (at your option) any later + version. + + This program is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + PARTICULAR PURPOSE. See the GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along with + this program; if not, write to the Free Software Foundation, Inc., 59 Temple + Place - Suite 330, Boston, MA 02111-1307, USA. + + The full text of the license can be found in the LICENSE file included with + this module, or in the L Pod as supplied with Perl 5.8.1 and later. + + =head1 SEE ALSO + + L + + =cut \end{verbatim} @@ -404,9 +404,9 @@ \begin{verbatim} -if ($a < $b || - $a > 2*$b) { - $x = ($a + $b + $c) + - sin($z); -} + if ($a < $b || + $a > 2*$b) { + $x = ($a + $b + $c) + + sin($z); + } \end{verbatim} @@ -427,10 +427,10 @@ \begin{verbatim} -someSub(longExpression1, longExpression2, longExpression3, - longExpression4, longExpression5); - -$var = someSub(longExpression1, - someSub(longExpression2, - longExpression3)); + someSub(longExpression1, longExpression2, longExpression3, + longExpression4, longExpression5); + + $var = someSub(longExpression1, + someSub(longExpression2, + longExpression3)); \end{verbatim} @@ -451,12 +451,12 @@ \begin{verbatim} -$alpha = (aLongBooleanExpression) ? $beta : $gamma; - -$alpha = (aLongBooleanExpression) ? $beta - : $gamma; - -$alpha = (aLongBooleanExpression) - ? $beta - : $gamma; + $alpha = (aLongBooleanExpression) ? $beta : $gamma; + + $alpha = (aLongBooleanExpression) ? $beta + : $gamma; + + $alpha = (aLongBooleanExpression) + ? $beta + : $gamma; \end{verbatim} @@ -475,7 +475,7 @@ \begin{verbatim} - if ($foo) { -# print("foo"); - } + if ($foo) { + # print("foo"); + } \end{verbatim} @@ -487,9 +487,9 @@ \begin{verbatim} -if (0) { - if ($foo) { - print("foo"); - } -} + if (0) { + if ($foo) { + print("foo"); + } + } \end{verbatim} @@ -531,5 +531,5 @@ \begin{verbatim} -# some words + # some words \end{verbatim} @@ -540,8 +540,8 @@ \begin{verbatim} -# this is the start of a multi-line comment that continues across a couple of -# lines then has a logical separation before another comment -# -# this is an adjoined comment + # this is the start of a multi-line comment that continues across a couple of + # lines then has a logical separation before another comment + # + # this is an adjoined comment \end{verbatim} @@ -557,9 +557,9 @@ \begin{verbatim} -if ($a == 2) { - return TRUE; # special case -} else { - return isPrime($a); # works only for odd a -} + if ($a == 2) { + return TRUE; # special case + } else { + return isPrime($a); # works only for odd a + } \end{verbatim} @@ -574,19 +574,19 @@ \begin{verbatim} -=item * reallyCoolSubroutine - -Accepts a real number and a string. Does some really cool stuff with it and -returns a really cool thing. - -=cut - -sub reallyCoolSubroutine -{ - my ($aNumber, $aString) = @_; - - # Do really cool stuff - - return $aThing; -} + =item * reallyCoolSubroutine + + Accepts a real number and a string. Does some really cool stuff with it and + returns a really cool thing. + + =cut + + sub reallyCoolSubroutine + { + my ($aNumber, $aString) = @_; + + # Do really cool stuff + + return $aThing; + } \end{verbatim} @@ -605,6 +605,6 @@ \begin{verbatim} -my $level; # indentation level -my $size; # size of table + my $level; # indentation level + my $size; # size of table \end{verbatim} @@ -612,5 +612,5 @@ \begin{verbatim} -my ($level, $size); + my ($level, $size); \end{verbatim} @@ -620,5 +620,5 @@ Do not put different types on the same line. Example: \begin{verbatim} -my ($foo, @fooArray); # AVOID! + my ($foo, @fooArray); # AVOID! \end{verbatim} @@ -630,11 +630,11 @@ \begin{verbatim} -my $count; -... -sub mySubroutine -{ - local $count; # AVOID! + my $count; ... -} + sub mySubroutine + { + local $count; # AVOID! + ... + } \end{verbatim} @@ -689,11 +689,11 @@ \begin{verbatim} -sub subName -{ - my ($param1, $param2, ...) = @_; - ... - - return $val; -} + sub subName + { + my ($param1, $param2, ...) = @_; + ... + + return $val; + } \end{verbatim} @@ -705,14 +705,17 @@ Each line should usually contain only one statement. Example: -\begin{verbatim} -$x = sqrt($x2); # Correct -$i++; # Correct -$x = sqrt($x2); $i++; # Avoid! + +\begin{verbatim} + $x = sqrt($x2); # Correct + $i++; # Correct + $x = sqrt($x2); $i++; # Avoid! \end{verbatim} An example of a reasonable two-statement line is: -\begin{verbatim} -$foo++; $bar--; -\end{verbatim} + +\begin{verbatim} + $foo++; $bar--; +\end{verbatim} + where the two actions are intimately related. @@ -737,10 +740,10 @@ \begin{verbatim} -return undef; # Correct -return; # Avoid! - -return $myDisk->size; - -return ($size ? $size : $defaultSize); + return undef; # Correct + return; # Avoid! + + return $myDisk->size; + + return ($size ? $size : $defaultSize); \end{verbatim} @@ -757,22 +760,23 @@ The \code{if-else} class of statements should have the following form: -\begin{verbatim} -if (condition) { - statements; -} - -if (condition) { - statements; -} else { - statements; -} - -if (condition) { - statements; -} elsif (condition) { - statements; -} else { - statements; -} + +\begin{verbatim} + if (condition) { + statements; + } + + if (condition) { + statements; + } else { + statements; + } + + if (condition) { + statements; + } elsif (condition) { + statements; + } else { + statements; + } \end{verbatim} @@ -782,7 +786,7 @@ \begin{verbatim} -for (initialization; condition; update) { - statements; -} + for (initialization; condition; update) { + statements; + } \end{verbatim} @@ -790,7 +794,7 @@ \begin{verbatim} -for (my $i = 0; $i < 100; $i++) { - print "$i\n"; -} + for (my $i = 0; $i < 100; $i++) { + print "$i\n"; + } \end{verbatim} @@ -799,5 +803,5 @@ \begin{verbatim} -for (initialization; condition; update) {} + for (initialization; condition; update) {} \end{verbatim} @@ -814,7 +818,7 @@ \begin{verbatim} -foreach my $item (@workingList) { - # do stuff with $item -} + foreach my $item (@workingList) { + # do stuff with $item + } \end{verbatim} @@ -823,7 +827,7 @@ \begin{verbatim} -foreach (@workingList) { # Avoid! - # do stuff with $_ -} + foreach (@workingList) { # Avoid! + # do stuff with $_ + } \end{verbatim} @@ -833,7 +837,7 @@ \begin{verbatim} -while (condition) { - statements; -} + while (condition) { + statements; + } \end{verbatim} @@ -841,5 +845,5 @@ \begin{verbatim} -while (condition) {} + while (condition) {} \end{verbatim} @@ -849,7 +853,7 @@ \begin{verbatim} -do { - statements; -} while (condition); + do { + statements; + } while (condition); \end{verbatim} @@ -860,9 +864,9 @@ \begin{verbatim} -MYLABEL: while (condition) { - if (condition) { - next MYLABEL; - } -} + MYLABEL: while (condition) { + if (condition) { + next MYLABEL; + } + } \end{verbatim} @@ -897,7 +901,7 @@ \begin{verbatim} -while (true) { - ... -} + while (true) { + ... + } \end{verbatim} @@ -916,5 +920,5 @@ $a += $c + $d; $a = ($a + $b) / ($c * $d); - + while ($d++ = $s++) { $n++; @@ -928,5 +932,5 @@ \begin{verbatim} - for (expr1; expr2; expr3) + for (expr1; expr2; expr3) {} \end{verbatim} @@ -936,5 +940,5 @@ \begin{verbatim} -my @things = qw( foo bar baz ); + my @things = qw( foo bar baz ); \end{verbatim} \end{itemize} @@ -1047,10 +1051,7 @@ \begin{verbatim} -package someModule; - -use base qw( Exporter ); - -our @EXPORT_OK = qw( $foo $bar ); - + use base qw( Exporter ); + + our @EXPORT_OK = qw( $foo $bar ); \end{verbatim} @@ -1067,6 +1068,6 @@ \begin{verbatim} -$row0 = $col0 = 0; -$sum = $sumx = $sumy = 0; + $row0 = $col0 = 0; + $sum = $sumx = $sumy = 0; \end{verbatim} @@ -1075,7 +1076,7 @@ \begin{verbatim} -if ($c++ = $d++) { # AVOID! - ... -} + if ($c++ = $d++) { # AVOID! + ... + } \end{verbatim} @@ -1083,19 +1084,21 @@ \begin{verbatim} -if (($c++ = $d++) != 0) { - ... -} + if (($c++ = $d++) != 0) { + ... + } \end{verbatim} Do not use embedded assignments in an attempt to improve run-time performance. This is the job of the compiler. Example: -\begin{verbatim} -$d = ($a = $b + $c) + $r; # AVOID! + +\begin{verbatim} + $d = ($a = $b + $c) + $r; # AVOID! \end{verbatim} should be written as -\begin{verbatim} -$a = $b + $c; -$d = $a + $r; + +\begin{verbatim} + $a = $b + $c; + $d = $a + $r; \end{verbatim} @@ -1111,6 +1114,6 @@ \begin{verbatim} -if ($a & $b || $c & $d) {} # AVOID! -if (($a & $b) || ($c & $d)) {} # RIGHT + if ($a & $b || $c & $d) {} # AVOID! + if (($a & $b) || ($c & $d)) {} # RIGHT \end{verbatim} @@ -1120,8 +1123,8 @@ \begin{verbatim} -if (($a == $b && $c == $d) || $e == $f) {} -$l << ($j + $k) -($l << $j) + $k -($i & $b) | $c + if (($a == $b && $c == $d) || $e == $f) {} + $l << ($j + $k) + ($l << $j) + $k + ($i & $b) | $c \end{verbatim} @@ -1131,9 +1134,9 @@ \begin{verbatim} -if (booleanExpression) { - return true; -} else { - return false; -} + if (booleanExpression) { + return true; + } else { + return false; + } \end{verbatim} @@ -1141,5 +1144,5 @@ \begin{verbatim} -return booleanExpression; + return booleanExpression; \end{verbatim} @@ -1148,5 +1151,5 @@ \begin{verbatim} -return (booleanExpression ? true : false); + return (booleanExpression ? true : false); \end{verbatim} @@ -1154,12 +1157,14 @@ \begin{verbatim} -if (condition) { - return $x; -} -return $y; -\end{verbatim} + if (condition) { + return $x; + } + return $y; +\end{verbatim} + should be written as -\begin{verbatim} -return (condition ? x : y); + +\begin{verbatim} + return (condition ? x : y); \end{verbatim} @@ -1170,5 +1175,5 @@ \begin{verbatim} -($x >= 0) ? $x : -$x; + ($x >= 0) ? $x : -$x; \end{verbatim}