Changeset 3090
- Timestamp:
- Jan 25, 2005, 11:44:01 AM (21 years ago)
- File:
-
- 1 edited
-
trunk/doc/misc/perlCodeConventions.tex (modified) (47 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/misc/perlCodeConventions.tex
r3042 r3090 1 %%% $Id: perlCodeConventions.tex,v 1.4 4 2005-01-18 23:25:08jhoblitt Exp $1 %%% $Id: perlCodeConventions.tex,v 1.45 2005-01-25 21:44:01 jhoblitt Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 13 13 \project{Pan-STARRS Image Processing Pipeline} 14 14 \organization{Institute for Astronomy} 15 \version{DR0 1}15 \version{DR02} 16 16 \docnumber{PSDC-430-010} 17 17 … … 26 26 \hline 27 27 DR01& 2004-12-01 & Second Draft\\ 28 \hline 29 DR02& 2005-01-24 & Third Draft\\ 28 30 \RevisionsEnd 29 31 … … 54 56 This document is derived from the Pan-STARRS IPP C Code Standards document 55 57 (PSDC 430-004), which is derived from the Sun Microsystems Java language coding 56 standards presented in the Java Language Specification\footnote{The Java 57 Language Specification - http://java.sun.com/docs/books/jls/index.html}. 58 standards presented in the \emph{Java Language Specification}\footnote{The 59 Java Language Specification - 60 \code{http://java.sun.com/docs/books/jls/index.html}}. 58 61 59 62 \begin{verbatim} … … 64 67 \end{verbatim} 65 68 66 See the Java Code Conventions Web site67 (\code{http://java.sun.com/docs/codeconv/})for more details.69 See the \emph{Java Code Conventions} web site\footnote{The Java Code 70 Conventions - \code{http://java.sun.com/docs/codeconv/}} for more details. 68 71 69 72 Such an adaption is explicitly permitted by the Sun Microsystems … … 79 82 common with Perl programmers. Instead, it is an attempt to make the C and Perl 80 83 coding styles as consistent as is reasonably feasible within the Pan-STARRS 81 project. This document contains only a brief discussion of Perl's 82 Object-Oriented features and none of it's more advanced features. 84 project. Further limiting the possible applicability of this document, only 85 language features that are deemed likely to be used by the Pan-STARRS project 86 are discussed. This has resulted in only a brief discussion of Perl's 87 Object-Oriented features and none of it's more advanced features (e.g. 88 AUTOLOAD). 83 89 84 90 \subsection{Applicability} 85 91 86 This document is intended to be relevant to Perl 5.8.0 or later.92 This document is intended to be relevant to Perl5, version 5.8.0 or later. 87 93 88 94 \subsection{Conformance} 89 95 90 96 If any of the conventions established in this document conflict with source 91 code that has been format ed by \code{perltidy} (see \S\ref{perltidy}), the97 code that has been formatted by \code{perltidy} (see \S\ref{perltidy}), the 92 98 formatting as output by \code{perltidy} will be considered to be in compliance 93 99 with the Perl Code Standards. … … 109 115 \subsection{File Suffixes} 110 116 111 Software uses the following file suffixes :117 Software uses the following file suffixes (in lowercase): 112 118 \begin{center} 113 119 \begin{tabular}{ll} … … 130 136 The preferred name for a file that invokes a ``build'' process. Typically this 131 137 calls \code{ExtUtils::MakeMaker} or \code{Module::Build} setup the the 132 necessary files to build and install a module or compile Swig generated C 133 code.\\ 138 necessary files to build and install a module or compile Swig generated C code. 139 \emph{The capitalized \code{.PL} suffix is reserved for build and configuration 140 scripts}\\ 134 141 \end{tabular} 135 142 \end{center} … … 152 159 \item 153 160 For an example of a properly formatted program, see 154 Complete Program Example(\S\ref{SourceExample}).161 \emph{Complete Program Example} (\S\ref{SourceExample}). 155 162 156 163 \item … … 164 171 \subsubsection{Perl Scripts} 165 172 166 Script files should have the following order:173 Script files should have, in the following order: 167 174 168 175 \begin{itemize} 169 176 \item 170 A Bourne shell ``she-bang'' for \code{perl}. \code{#!/usr/bin/perl}.177 A Bourne shell ``she-bang'' for \code{perl}. e.g. \code{#!/usr/bin/perl}. 171 178 172 179 \item … … 194 201 195 202 \item 196 Any script level "globals" declared as lexical variables. e.g. \code{my $foo} 203 Any script level ``globals'' declared as lexical variables. e.g. \code{my $foo} 204 205 \item 206 The functional ``body'' of the script. This where command line parameter 207 parsing, subroutine calls, etc. are placed. 197 208 198 209 \item … … 207 218 \end{itemize} 208 219 209 For an example of a properly organized script, see Script File Example220 For an example of a properly organized script, see \emph{Script File Example} 210 221 (\S\ref{foo.pl}). 211 222 212 223 \subsubsection{Perl Modules} 213 224 214 Module files should have the following order:225 Module files should have, in the following order: 215 226 216 227 \begin{itemize} … … 262 273 \end{itemize} 263 274 264 For an example of a properly organized module, see Module File Example275 For an example of a properly organized module, see \emph{Module File Example} 265 276 (\S\ref{Foo.pm}). 266 277 … … 308 319 \end{itemize} 309 320 310 For an example of a properly organized Pod, see Pod File Example321 For an example of a properly organized Pod, see \emph{Pod File Example} 311 322 (\S\ref{Foo.pod}). 312 323 … … 345 356 \item Prefer higher-level breaks to lower-level breaks. 346 357 347 \item Indent new lines 4 spaces deeper than the nesting depth of the line on348 which the expression began.358 \item Indent new lines 1 indentation unit deeper than the nesting depth of the 359 line on which the expression began. 349 360 350 361 \item If it is convenient to list one statement per line (similar to a hash … … 378 389 \end{verbatim} 379 390 380 Here are three acceptable ways to format ternary expressions: 391 Below are three acceptable ways to format ternary expressions. 392 \emph{Expression fragments should be indented such that \code{?} and \code{:} 393 are aligned vertically (as opposed to being indented a fixed number of 394 indentation units).} 381 395 382 396 \begin{verbatim} … … 399 413 400 414 Comments should not be used to comment out large sections of code. When 401 deactivating 2or fewer consecutive lines of code a double hash (\code{##})415 deactivating 3 or fewer consecutive lines of code a double hash (\code{##}) 402 416 should be used at the very beginning of the line(s). 403 417 … … 410 424 \end{verbatim} 411 425 412 When deactivating 3or more lines of code an embedded Pod statement should be426 When deactivating 4 or more lines of code an embedded Pod statement should be 413 427 used. The opening statement should be \code{=for off} and the closing 414 428 statement should be \code{=cut}. The deactivated section should remain nested … … 478 492 \begin{verbatim} 479 493 # this is the start of a multi-line comment that continues across a couple of 480 # lines then has a logical separation before another comment494 # lines, then has a logical separation before another comment 481 495 # 482 496 # this is an adjoined comment … … 491 505 separated from the closing semi-colon by a single space. 492 506 493 Here's an example of a trailing comment in Perl code:507 Here's an example trailing comments: 494 508 495 509 \begin{verbatim} … … 512 526 513 527 Plain Old Documentation format or Pod will be used to produce documentation of 514 the subroutines and variables in the exposed API. See Plain Old Documentation515 (\S\ref{pod}).516 517 If you need to give information about a interface, or variable that isn't528 the subroutines and variables in the exposed API. See \emph{Plain Old 529 Documentation} (\S\ref{pod}). 530 531 If you need to give information about an interface, or variable that isn't 518 532 appropriate for Podification, use a normal implementation single-line or 519 multi-line comment immediately \ textit{before} the code (as exampled above).533 multi-line comment immediately \emph{before} the code (as exampled above). 520 534 521 535 … … 536 550 537 551 \begin{verbatim} 538 my ($level, $size); 552 my ($level, $size); # AVOID! 539 553 \end{verbatim} 540 554 … … 588 602 \end{verbatim} 589 603 590 Consider using the \code{qw} operator when assigning strings to an array. 604 Consider using the \code{qw} operator to avoid repetitive string quoting when 605 assigning to an array. 591 606 592 607 \begin{verbatim} … … 643 658 \end{verbatim} 644 659 645 \emph{This restriction does not apply to Perl's built in variables.} 660 \emph{This restriction does not apply to Perl's built-in variables or the 661 package variable used by some modules to control global behavior.} 646 662 647 663 \subsection{Package Variables} 648 664 649 See When to Make Symbols Global(\S\ref{globals}).665 See \emph{When to Make Symbols Global} (\S\ref{globals}). 650 666 651 667 \subsection{Initialization} … … 658 674 659 675 \item 660 Do not initialize variables with an empty string or list -this is pointless.676 Do not initialize variables with an empty string or list; this is pointless. 661 677 662 678 \item … … 675 691 This allows them to be initialized as they are created, and naturally 676 692 associates their declaration with their use. 693 694 Practical examples of when \emph{not} to place variable declarations at the top 695 of a block include loop iterators, intermediate value variables, and 696 variables used for returning values from nested scopes. 677 697 678 698 \subsection{Subroutine Declarations} … … 752 772 where the two actions are intimately related. 753 773 774 \subsubsection{return Statements} 775 776 A \code{return} statement should not use parentheses unless they make the 777 return value more obvious in some way. All subroutines must have an explicit, 778 non-null, return statement unless they are returning an error condition, in 779 which case a bare \code{return} is acceptable. Example: 780 781 \begin{verbatim} 782 return $a; # Correct 783 return; # Correct only if indicating an error 784 return $myDisk->size; # Correct 785 return ($size ? $size : $defaultSize); # Correct 786 return($a); # AVOID! 787 return ($a); # AVOID! 788 \end{verbatim} 789 790 \emph{In the absence of an explicit return statement Perl will return the 791 results of the last statement executed. Relying on this behavior is likely to 792 confuse maintenance programmers and therefore should be avoided.} 793 794 Try to make the structure of your program match the intent. Example: 795 796 \begin{verbatim} 797 if (booleanExpression) { 798 return true; 799 } else { 800 return false; 801 } 802 \end{verbatim} 803 804 should instead be written as 805 806 \begin{verbatim} 807 return booleanExpression; 808 \end{verbatim} 809 810 If you're concerned that the reader may not know that \code{booleanExpression} 811 is boolean, use: 812 813 \begin{verbatim} 814 return (booleanExpression ? true : false); 815 \end{verbatim} 816 817 Similarly, 818 819 \begin{verbatim} 820 if (condition) { 821 return $x; 822 } 823 return $y; 824 \end{verbatim} 825 826 should be written as 827 828 \begin{verbatim} 829 return (condition ? x : y); 830 \end{verbatim} 831 754 832 \subsection{Compound Statements} 755 833 … … 765 843 \end{itemize} 766 844 767 \subsection{return Statements} 768 769 A \code{return} statement with a value should not use parentheses unless they 770 make the return value more obvious in some way. All subroutines must have an 771 explicit, non-null, return statement. Example: 772 773 \begin{verbatim} 774 return undef; # Correct 775 return; # AVOID! 776 return $myDisk->size; # Correct 777 return ($size ? $size : $defaultSize); # Correct 778 \end{verbatim} 779 780 \emph{In the absence of an explicit return statement Perl will return the 781 results of the last statement executed. A null \code{return} statement also 782 causes the result of the last statement executed to be returned. Relying on 783 this behavior is likely to confuse maintenance programmers and therefore should 784 be avoided.} 785 786 \subsection{if, if-else, if-elsif-else Statements} 787 788 \code{if} statements must always use parentheses \code{()} around conditionals. 845 \subsubsection{if, if-else, if-elsif-else Statements} 789 846 790 847 The \code{if-else} class of statements should have the following form: … … 810 867 \end{verbatim} 811 868 812 \subsection{C style for Statements} 869 \emph{The same formatting applies to \code{unless}, \code{unless-else}, \& 870 \code{unless-elsif-else} statements.} 871 872 \subsubsection{C style for Statements} 813 873 814 874 A \code{for} statement should have the following form: … … 829 889 830 890 An empty \code{for} statement (one in which all the work is done in the 831 initialization, condition, and update clauses) should have the following form s:891 initialization, condition, and update clauses) should have the following form: 832 892 833 893 \begin{verbatim} … … 841 901 the loop (for the update clause). 842 902 843 \subsection{Perl style for, foreach Statements} 903 \emph{Generally, ``Perlish'' style loops are preferred over the C form.} 904 905 \subsubsection{Perl style for, foreach Statements} 844 906 845 907 A Perlish \code{for} or \code{foreach} statement should have the following … … 848 910 \begin{verbatim} 849 911 foreach my $item (@workingList) { 850 # do stuff with $item 912 statements; 913 } 914 915 foreach my $item (@workingList) { 916 statements; 917 } continue { 918 statements; 851 919 } 852 920 \end{verbatim} 853 921 854 922 The current working item should be interacted with through a declared lexical 855 variable and 923 variable and not via \code{$_}. 856 924 857 925 \begin{verbatim} … … 861 929 \end{verbatim} 862 930 863 \subs ection{while Statements}931 \subsubsection{while Statements} 864 932 865 933 A \code{while} statement should have the following form: … … 869 937 statements; 870 938 } 939 940 while (condition) { 941 statements; 942 } continue { 943 statements; 944 } 945 \end{verbatim} 946 947 Do \emph{not} use \code{$_} when iterating through a filehandle. Instead, place 948 each ``line'' of the filehandle into a named lexical variable. 949 950 \begin{verbatim} 951 my $line; 952 while (defined($line = <FILE>)) { 953 statements; 954 } 871 955 \end{verbatim} 872 956 … … 877 961 \end{verbatim} 878 962 879 \subsection{do-while Statements} 880 881 A \code{do-while} statement should have the following form: 963 \emph{Consider using the \code{map} subroutine instead of a loop for list 964 generation.} 965 966 \subsubsection{do Statements} 967 968 In Perl \code{do} is a built-in subroutine. Traditional \code{do-while} like 969 statements may be constructed with it by using Statement Modifiers (see 970 \S\ref{statement-modifiers}) in the following form: 882 971 883 972 \begin{verbatim} 884 973 do { 885 974 statements; 886 } while(condition);887 \end{verbatim} 888 889 \subs ection{Label Statements}890 891 Code labels should be indented to align with the previous level of 892 indentation.975 } statement-modifier (condition); 976 \end{verbatim} 977 978 \subsubsection{Label Statements} 979 980 Code labels should be indented to align with the previous level of indentation. 981 Do \emph{not} label a loop unless you are going to use the label. 893 982 894 983 \begin{verbatim} … … 900 989 \end{verbatim} 901 990 902 \subs ection{Blocks}903 904 The conten se of a block should be idented one level.991 \subsubsection{Blocks} 992 993 The contents of a block should be indented one level. 905 994 906 995 \begin{verbatim} … … 912 1001 \end{verbatim} 913 1002 1003 \subsection{Statement Modifiers} 1004 \label{statement-modifiers} 1005 1006 These keywords are considered acceptable for use as ``Statement Modifiers'': 1007 \code{if}, \code{unless} \& \code{until}. These keywords should generally be 1008 avoided for that purpose: \code{while} \& \code{foreach}. 1009 1010 Statement Modifiers should only be used \emph{only} when it makes the intent 1011 for the code more obvious. e.g. 1012 1013 \begin{verbatim} 1014 die "you forgot to handle some case" unless $flag; # Correct 1015 $a = 1 if (($b == $c) && defined($d); # AVOID! 1016 \end{verbatim} 1017 1018 Parenthesis should be used with complex expressions. 1019 1020 \begin{verbatim} 1021 someSubCall($a, $b, $c) if ($foo eq 'bar' || $baz > 10); # Correct 1022 someSubCall($a, $b, $c) if $foo eq 'bar' || $baz > 10; # AVOID! 1023 \end{verbatim} 1024 914 1025 915 1026 %------------------------------------------------------------------------------ 916 1027 917 1028 \section{White Space} 1029 1030 In general, be very liberal in the use of whitespace, both horizontal and 1031 vertical, if it will improve the clarity and readability of your code. 1032 918 1033 \subsection{Blank Lines} 919 1034 … … 921 1036 are logically related. 922 1037 923 Two blank lines should always be used in the following circumstances: 924 \begin{itemize} 925 \item 926 Between sections of a source file 927 \end{itemize} 1038 Two blank lines should always be used between sections of a source file. 928 1039 929 1040 One blank line should always be used in the following circumstances: … … 992 1103 \end{itemize} 993 1104 994 Blank spaces should \ textit{not} be used in the following circumstances:1105 Blank spaces should \emph{not} be used in the following circumstances: 995 1106 996 1107 \begin{itemize} … … 1027 1138 1028 1139 The filenames of all scripts should be verbal phrases, in mixed case. The 1029 capitalized \code{.PL} suffix is reserved for ``build''scripts.1140 capitalized \code{.PL} suffix is reserved for build and configuration scripts. 1030 1141 1031 1142 & … … 1083 1194 of a variable name should be mnemonic- that is, designed to indicate to the 1084 1195 casual observer the intent of its use. One-character variable names should be 1085 avoided except for temporary \ textit{throwaway} variables. Common names for1196 avoided except for temporary \emph{throwaway} variables. Common names for 1086 1197 temporary variables are \code{$i}, \code{$j}, \code{$k}, \code{$m}, and \code{$n} 1087 1198 for integers; \code{$c}, \code{$d}, and \code{$e} for characters. … … 1238 1349 \end{verbatim} 1239 1350 1240 \subsubsection{Returning Values}1241 1242 Try to make the structure of your program match the intent. Example:1243 1244 \begin{verbatim}1245 if (booleanExpression) {1246 return true;1247 } else {1248 return false;1249 }1250 \end{verbatim}1251 1252 should instead be written as1253 1254 \begin{verbatim}1255 return booleanExpression;1256 \end{verbatim}1257 1258 If you're concerned that the reader may not know that \code{booleanExpression}1259 is boolean, use:1260 1261 \begin{verbatim}1262 return (booleanExpression ? true : false);1263 \end{verbatim}1264 1265 Similarly,1266 1267 \begin{verbatim}1268 if (condition) {1269 return $x;1270 }1271 return $y;1272 \end{verbatim}1273 1274 should be written as1275 1276 \begin{verbatim}1277 return (condition ? x : y);1278 \end{verbatim}1279 1280 1351 \subsubsection{Expressions before `?' in the Conditional Operator } 1281 1352 … … 1298 1369 \end{verbatim} 1299 1370 1300 \subsubsection{File Handles}1371 \subsubsection{Filehandles} 1301 1372 1302 1373 Do not use ``bare-words'' as filehandles except for \code{STDIN}, \code{STDOUT}, … … 1383 1454 \subsubsection{Inheritance} 1384 1455 1385 Do not use the \code{@ISA} package variable for sub classing. Instead, use the1456 Do not use the \code{@ISA} package variable for sub-classing. Instead, use the 1386 1457 \code{base} pragma. 1387 1458 … … 1439 1510 1440 1511 \item 1441 Consider using the \code{q} and \code{qq} operators instead of backslashes1442 (\code{\}) when quoting strings that contain other quotes or b lackslases.1512 Consider using the \code{q} and \code{qq} operators instead of backslashes 1513 (\code{\}) when quoting strings that contain other quotes or backslashes. 1443 1514 1444 1515 \item 1445 1516 Consider using the \code{quotemeta} subroutine when handling strings that 1446 contain meta-characters. 1447 \end{itemize} 1517 contain meta-characters. \end{itemize} 1448 1518 1449 1519 \subsubsection{String Concatenation} … … 1483 1553 1484 1554 \begin{verbatim} 1485 sub myopen (*;$) # AVOID! 1555 sub myopen (*;$); # AVOID! 1556 sub myopen (*;$) { } # AVOID! 1486 1557 \end{verbatim} 1487 1558 … … 1543 1614 http://search.cpan.org/~drolsky/Params-Validate/} is a Perl module that allows 1544 1615 you to perform rigorous subroutine parameter validation. It is highly 1545 configurable and validation may be deactivated at runtime 1616 configurable and validation may be deactivated at runtime. 1546 1617 1547 1618 The basic premise is that a validation specification is passed to one of
Note:
See TracChangeset
for help on using the changeset viewer.
