Changeset 2359
- Timestamp:
- Nov 12, 2004, 4:57:30 PM (22 years ago)
- File:
-
- 1 edited
-
trunk/doc/misc/perlCodeConventions.tex (modified) (33 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/misc/perlCodeConventions.tex
r2356 r2359 1 %%% $Id: perlCodeConventions.tex,v 1.1 0 2004-11-12 22:31:58jhoblitt Exp $1 %%% $Id: perlCodeConventions.tex,v 1.11 2004-11-13 02:57:30 jhoblitt Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 30 30 %%% References here. 31 31 \textbf{\PS{} ID} & \textbf{Title} & \textbf{Author} \\ 32 \hline 32 33 430-004 &Pan-STARRS IPP C Code Standards &Robert Lupton\\ 33 34 \hline … … 66 67 \subsection{Limitations} 67 68 68 Although Perl's syntax is in many ways similar to that of C or Java, there are69 manysignification deviations. This has lead to a coding style within the Perl69 Although Perl's syntax is similar to that of C or Java, there are many 70 signification deviations. This has lead to a coding style within the Perl 70 71 community that is generally significantly different then that used for C or 71 72 Java (See the \code{perlstyle} Pod in the standard Perl documentation for an … … 73 74 common with Perl programmers. Instead, it is an attempt to make the C and Perl 74 75 coding styles as consistent as is reasonably feasible within the Pan-STARRS 75 project. 76 project. This document also only contains brief discussion of Perl's 77 Object-Oriented features and none of Perl's more advanced features. 78 79 \subsection{Applicability} 80 81 This document is intended to be relevant with Perl 5.8.0 or later. 76 82 77 83 \subsection{To whom should I Complain?} … … 131 137 \subsubsection{Perl Scripts} 132 138 133 Includefiles should have the following order:139 Script files should have the following order: 134 140 135 141 \begin{itemize} 136 142 \item 137 143 A Bourne shell "she-bang" for perl. \code{#!/usr/bin/perl}. 144 138 145 \item 139 146 A Copyright notice followed by a blank commented line. Then one commented line 140 147 per CVS keyword to be expanded. 148 149 \item 150 A minimum perl version requirement in long form (vStrings are not allowed). 151 Where \code(requirement = revision + version / 1000 + subversion / 152 1\_000\_000). E.g. A minimum requirement of Perl 5.8.5 would be expressed as 153 \code{use 5.008005} 154 155 \item 156 A \code{use strict} and \code{use warnings} declaration. 157 158 \item 159 Any base classes. 160 161 \item 162 Any constant declarations. 163 164 \item 165 Any script level "globals" declared as lexical variables. E.g. \code{my $foo} 166 167 \item 168 Any subroutines. 169 170 \item 171 A \code{__END__} token to instruct the perl parser to stop looking for 172 executable code. 173 174 \item 175 Any Pod documentation about the script. 176 \end{itemize} 177 178 e.g. for file \file{foo.pl}: 179 180 \scriptsize 181 \code{#!/usr/bin/perl}\\ 182 \\ 183 \code{# Copyright (C) 2004 Joshua Hoblitt}\\ 184 \code{#}\\ 185 \code{# $}\code{Id$}\\ 186 \normalsize 187 \begin{verbatim} 188 use 5.008005; # optional 189 190 use strict; # not optional 191 use warnings; # not optional 192 193 use Foo qw( $bar ); 194 195 use constant MAXFOO => 3; 196 197 my $baz; 198 199 sub fuu 200 { 201 202 } 203 204 __END__ 205 206 ... 207 \end{verbatim} 208 209 \subsubsection{Perl Modules} 210 211 Perl Module/Namespaces deviate slightly from the standard naming conventions in 212 that the first character is always capitalized. 213 214 \begin{itemize} 215 \item 216 A Copyright notice followed by a blank commented line. Then one commented line 217 per CVS keyword to be expanded. 218 219 \item 220 A Perl \code{package} declaration. 221 141 222 \item 142 223 A minimum perl version requirement in long form (vStrings are not allowed). … … 144 225 E.g. A minimum requirement of Perl 5.8.5 would be expressed as \code{use 145 226 5.008005} 227 146 228 \item 147 229 A \code{use strict} and \code{use warnings} declaration. 230 148 231 \item 149 232 Any modules to include. 233 234 \item 235 Any constant declarations. 236 150 237 \item 151 238 Any script level "globals" declared as lexical variables. E.g. \code{my $foo} 239 152 240 \item 153 241 Any subroutines. 242 243 \item 244 A \code{1} on a line by itself so when the module is parsed it always ends with 245 a true expression. 246 154 247 \item 155 248 A \code{__END__} token to instruct the perl parser to stop looking for 156 249 executable code. 157 \item Any Pod documentation about the script. 250 251 \item 252 Any Pod documentation about the module. 158 253 \end{itemize} 159 254 160 e.g. for file \file{foo.pl}: 161 162 \begin{verbatim} 163 #!/usr/bin/perl 164 165 # Copyright (C) 2004 Joshua Hoblitt 166 # 167 # $Id: perlCodeConventions.tex,v 1.10 2004-11-12 22:31:58 jhoblitt Exp $ 255 e.g. for file \file{Foo.pm}: 256 257 \scriptsize 258 \code{# Copyright (C) 2004 Joshua Hoblitt}\\ 259 \code{#}\\ 260 \code{# $}\code{Id$}\\ 261 \normalsize 262 \begin{verbatim} 263 package Foo; 168 264 169 265 use 5.008005; # optional … … 172 268 use warnings; # not optional 173 269 270 use base qw( Baz ); 271 174 272 use Foo qw( $bar ); 273 274 use constant MAXFOO => 3; 175 275 176 276 my $baz; … … 181 281 } 182 282 283 1; 284 183 285 __END__ 184 \end{verbatim} 185 186 \subsubsection{Perl Modules} 187 188 Perl module names deviate slightly from the other naming conventions in that 189 the first character is always capitalized. 190 191 \begin{itemize} 192 \item 193 A Copyright notice followed by a blank commented line. Then one commented line 194 per CVS keyword to be expanded. 195 \item 196 A Perl Package declaration. \code{package Foo} 197 \item 198 A minimum perl version requirement in long form (vStrings are not allowed). 199 Where \code(requirement = revision + version / 1000 + subversion / 1\_000\_000). 200 E.g. A minimum requirement of Perl 5.8.5 would be expressed as \code{use 201 5.008005} 202 \item 203 A \code{use strict} and \code{use warnings} declaration. 204 \item 205 Any modules to include. 206 \item 207 Any script level "globals" declared as lexical variables. E.g. \code{my $foo} 208 \item 209 Any subroutines. 210 \item 211 A \code{1} on a line by itself so when the module is parsed it always ends with 212 a true expression. 213 \item 214 A \code{__END__} token to instruct the perl parser to stop looking for 215 executable code. 216 \item Any Pod documentation about the module. 217 \end{itemize} 218 219 e.g. for file \file{Foo.pm}: 220 221 \begin{verbatim} 222 # Copyright (C) 2004 Joshua Hoblitt 223 # 224 # $Id: perlCodeConventions.tex,v 1.10 2004-11-12 22:31:58 jhoblitt Exp $ 225 226 package Foo; 227 228 use 5.008005; # optional 229 230 use strict; # not optional 231 use warnings; # not optional 232 233 use Foo qw( $bar ); 234 235 my $baz; 236 237 sub fuu 238 { 239 240 } 241 242 1; 243 244 __END__ 286 287 ... 245 288 \end{verbatim} 246 289 … … 328 371 =cut 329 372 \end{verbatim} 373 330 374 331 375 %------------------------------------------------------------------------------ … … 410 454 \end{verbatim} 411 455 456 412 457 %------------------------------------------------------------------------------ 413 458 … … 421 466 422 467 Example of deactivating a single line code. 468 423 469 \begin{verbatim} 424 470 if ($foo) { … … 432 478 433 479 Example of deactivating multiple lines of code. 480 434 481 \begin{verbatim} 435 482 if (0) { … … 475 522 476 523 Example of a single-line comment. 524 477 525 \begin{verbatim} 478 526 # some words … … 486 534 \label{col41} 487 535 488 Very short comments can appear on the same line as the code they 489 describe, and should be indented to column 41\footnote{In emacs, this 490 may be achieved with \code{ESC;}}. If the code extends beyond this 491 column, the comment should be separated from the closing semi-colon by 492 a single space. 536 Very short comments can appear on the same line as the code they describe, and 537 should be indented to column 41\footnote{In emacs, this may be achieved with 538 \code{ESC;}}. If the code extends beyond this column, the comment should be 539 separated from the closing semi-colon by a single space. 493 540 494 541 Here's an example of a trailing comment in Perl code: 542 495 543 \begin{verbatim} 496 544 if ($a == 2) { … … 532 580 multi-line comment immediately \textit{before} the code (as exampled above). 533 581 582 534 583 %------------------------------------------------------------------------------ 535 584 536 585 \section{Declarations} 537 586 538 All globally-visible symbols must be declared in a suitable header539 (.h) file. Global private symbols should not appear in public header540 files, but rather in separate, private header files.541 542 587 \subsection{Lexical Variables} 543 588 544 One declaration per line with a single place between 'my'and the identifier.589 One declaration per line with a single place between \code{my} and the identifier. 545 590 546 591 \begin{verbatim} … … 560 605 Do not put different types on the same line. Example: 561 606 \begin{verbatim} 562 my ($foo, 607 my ($foo, @fooArray); # WRONG! 563 608 \end{verbatim} 564 609 … … 614 659 \item 615 660 The first line after the opening brace should declare a list of lexical 616 variables for input parameters and assign \code{@ \_} to it.661 variables for input parameters and assign \code{@_} to it. 617 662 618 663 \item … … 634 679 } 635 680 \end{verbatim} 681 636 682 637 683 %------------------------------------------------------------------------------ … … 679 725 \begin{verbatim} 680 726 return undef; # Correct 681 return; # Wrong!727 return; # Avoid! 682 728 683 729 return $myDisk->size; … … 687 733 688 734 Note: In absence of an explicit return statement Perl will return the results 689 of the last statement executed. A null return statement \code{return;} also690 causes theresult of the last statement executed to be returned.735 of the last statement executed. A null \code{return} statement causes the 736 result of the last statement executed to be returned. 691 737 692 738 \subsection{if, if-else, if elsif else Statements} … … 747 793 the loop (for the update clause). 748 794 795 \subsection{Perl style for, foreach Statements} 796 797 \begin{verbatim} 798 \end{verbatim} 799 749 800 \subsection{while Statements} 750 801 751 802 A \code{while} statement should have the following form: 803 752 804 \begin{verbatim} 753 805 while (condition) { … … 755 807 } 756 808 \end{verbatim} 809 757 810 An empty \code{while} statement should have the following form: 811 758 812 \begin{verbatim} 759 813 while (condition) {} … … 763 817 764 818 A \code{do-while} statement should have the following form: 819 765 820 \begin{verbatim} 766 821 do { … … 773 828 Code labels should be indented to align with the previous level of 774 829 indentation. 830 831 \begin{verbatim} 832 MYLABEL: while (condition) { 833 if (condition) { 834 next; 835 } 836 } 837 \end{verbatim} 838 775 839 776 840 %------------------------------------------------------------------------------ … … 816 880 \item 817 881 Binary operators should be separated from their operands by spaces. Blank 818 spaces should never separate unary operators such as a type cast, unary minus,819 increment(\code{++}), and decrement (\code{--}) from their operands. Examples:882 spaces should never separate unary operators such as a unary minus, increment 883 (\code{++}), and decrement (\code{--}) from their operands. Examples: 820 884 821 885 \begin{verbatim} … … 850 914 \section{Naming Conventions} 851 915 852 Naming conventions make programs more understandable by making them 853 easier to read. They can also give information about the subroutine of 854 the identifier -- for example, whether it's a constant, a subroutine, or 855 a type -- which can be helpful in understanding the code. Remember 856 these are guidelines for improving readability; clarity should trump 857 rigid adherence to the guideline. 916 Naming conventions make programs more understandable by making them easier to 917 read. They can also give information about the subroutine of the identifier -- 918 for example, whether it's a constant or a subroutine -- which can be helpful in 919 understanding the code. Remember these are guidelines for improving 920 readability; clarity should trump rigid adherence to the guideline. 858 921 859 922 { \small … … 876 939 \code{runFast();}\hfil\break 877 940 \code{getBackground();}\hfil\break 941 \code{_keepHandsOff();}\hfil\break 942 \code{_notForPublicUse();}\hfil\break 878 943 879 944 \\ … … 881 946 Variables & 882 947 883 Except for variables, all instance, class, and class constants are in mixed 884 case with Variable names should not start with underscore \code{_} as these 885 names are, under some circumstances, reserved by Perl community convention. 886 887 Variable names should be short yet meaningful. The choice of a variable name 888 should be mnemonic- that is, designed to indicate to the casual observer the 889 intent of its use. One-character variable names should be avoided except for 890 temporary \textit{throwaway} variables. Common names for temporary variables 891 are \code{i}, \code{j}, \code{k}, \code{m}, and \code{n} for integers; 892 \code{c}, \code{d}, and \code{e} for characters. 948 Variable names should be in mixed case and be short yet meaningful. The choice 949 of a variable name should be mnemonic- that is, designed to indicate to the 950 casual observer the intent of its use. One-character variable names should be 951 avoided except for temporary \textit{throwaway} variables. Common names for 952 temporary variables are \code{$i}, \code{$j}, \code{$k}, \code{$m}, and \code{$n} 953 for integers; \code{$c}, \code{$d}, and \code{$e} for characters. 893 954 894 955 & … … 905 966 Constants & 906 967 907 Perl's \code{constant} pragma should not be used as it merely generates 908 subroutines with null prototypes. 'Constants' created this way can not be 909 interpolated instead of strings. Instead, use Lexical variables but with all 910 capital letters. 968 Perl's \code{constant} pragma should be used to declare constants. Note: 969 'constants' created this way can not be interpolated inside of double quoted 970 strings. 911 971 912 972 & 913 \code{ my $MAXLEN =40;}\hfil\break914 \code{ my @LENGTH =(2, 4, 8);}\hfil\break915 \code{ my %CLASS =(raw => 1, processed => 2);}\hfil\break973 \code{use constant MAXLEN => 40;}\hfil\break 974 \code{use constant LENGTH => qw(2, 4, 8);}\hfil\break 975 \code{use constant CLASSES => (raw => 1, processed => 2);}\hfil\break 916 976 917 977 \\ … … 924 984 & 925 985 926 \code{ Class::Data::Inheritable}\hfil\break927 \code{ Time::HiRes}\hfil\break928 \code{ XML::SimpleObject}\hfil\break986 \code{package Class::Data::Inheritable;}\hfil\break 987 \code{package Time::HiRes;}\hfil\break 988 \code{package XML::SimpleObject;}\hfil\break 929 989 930 990 \\ … … 932 992 \end{tabular} 933 993 } 994 934 995 935 996 %------------------------------------------------------------------------------ … … 1012 1073 \end{verbatim} 1013 1074 1014 There are some famous problems with precedence in C. In particular, 1015 expressions involving the combinations of \code{||} and \code{&&} should be 1016 fully parenthesized, as should all expressions containingbitwise operators:1075 In particular, expressions involving the combinations of \code{||} and 1076 \code{&&} should be fully parenthesized, as should all expressions containing 1077 bitwise operators: 1017 1078 1018 1079 \begin{verbatim} … … 1070 1131 \end{verbatim} 1071 1132 1133 \end{document} 1072 1134 %------------------------------------------------------------------------------ 1073 1135 \appendix %Begin Appendices
Note:
See TracChangeset
for help on using the changeset viewer.
