Changeset 2373 for trunk/doc/misc/perlCodeConventions.tex
- Timestamp:
- Nov 15, 2004, 6:58:16 PM (22 years ago)
- File:
-
- 1 edited
-
trunk/doc/misc/perlCodeConventions.tex (modified) (29 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/misc/perlCodeConventions.tex
r2363 r2373 1 %%% $Id: perlCodeConventions.tex,v 1.1 5 2004-11-13 03:39:25jhoblitt Exp $1 %%% $Id: perlCodeConventions.tex,v 1.16 2004-11-16 04:58:16 jhoblitt Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 69 69 Although Perl's syntax is similar to that of C or Java, there are many 70 70 signification deviations. This has lead to a coding style within the Perl 71 community that is generally significantly different th en that used for C or71 community that is generally significantly different than that used for C or 72 72 Java (See the \code{perlstyle} Pod in the standard Perl documentation for an 73 73 example of this). This document does not attempt to define the coding style … … 86 86 complaints it may generate. 87 87 88 \code{ rhl@astro.princeton.edu}.88 \code{<rhl@astro.princeton.edu>}. 89 89 90 90 %------------------------------------------------------------------------------ … … 101 101 \textbf{File Type}& \textbf{Suffix}\\ 102 102 \hline 103 Perl scripts& \code{.pl}\\104 Perl modules& \code{.pm}\\105 P erl documentation&\code{.pod}\\103 Perl scripts& \code{.pl}\\ 104 Perl modules& \code{.pm}\\ 105 Plain old documentation& \code{.pod}\\ 106 106 \end{tabular} 107 107 \end{center} … … 133 133 Source File Example (\S\ref{SourceExample}). 134 134 135 ``Scripts'' have user documentation included at the end of the file. 136 137 ``Modules'' have documentation included in a companion \code{.pod}. 138 135 139 \subsection{Source Files} 136 140 … … 186 190 \normalsize 187 191 \begin{verbatim} 188 use 5.008005; # optional189 190 use strict; # not optional191 use warnings; # not optional192 193 use Foo qw( $bar ); 194 195 use constant MAXFOO => 3; 196 197 my $baz; 192 use 5.008005; # optional 193 194 use strict; # not optional 195 use warnings; # not optional 196 197 use Foo qw( $bar ); # import $bar into our namespace 198 199 use constant MAXFOO => 3; # maximum number of foos 200 201 my $baz; # is a lexical variable in the top level scope 198 202 199 203 sub fuu … … 236 240 237 241 \item 238 Any script level "globals" declared as lexical variables. E.g. \code{my $foo} 242 Any script level ``globals'' declared as lexical variables. E.g. \code{my 243 $foo} 239 244 240 245 \item … … 248 253 A \code{__END__} token to instruct the perl parser to stop looking for 249 254 executable code. 250 251 \item252 Any Pod documentation about the module.253 255 \end{itemize} 254 256 … … 263 265 package Foo; 264 266 265 use 5.008005; # optional266 267 use strict; # not optional268 use warnings; # not optional269 270 use base qw( Baz ); 271 272 use Foo qw( $bar ); 273 274 use constant MAXFOO => 3; 275 276 my $baz; 267 use 5.008005; # optional 268 269 use strict; # not optional 270 use warnings; # not optional 271 272 use base qw( Baz ); # become a subclass of Baz 273 274 use Foo qw( $bar ); # import $bar into our namespace 275 276 use constant MAXFOO => 3; # maximum number of foos 277 278 my $baz; # is a lexical variable in the top level scope 277 279 278 280 sub fuu … … 284 286 285 287 __END__ 286 287 ... 288 \end{verbatim} 289 290 \subsubsection{Perl Documentation} 291 292 In most cases documentation should be included as ether in-line Pod or after 293 the \code{__END__} token in a \code{.pl} file. The format for documentation 294 embedded in a \code{.pl} file after the \code{__END__} token or as a stand 295 alone file is as follows: 288 \end{verbatim} 289 290 \subsubsection{Plain Old Documentation} 291 292 This is the format for documentation in a \code{.pl} file after the 293 \code{__END__} token and the \code{.pod} file that should accompany a 294 a module (\code{.pm}). 296 295 297 296 e.g. for file Foo.pod: … … 412 411 \item Align the new line with the beginning of the expression at the 413 412 same level on the previous line\footnote{For emacs users, this means 414 the indentation that \code{<tab>} produces}.413 the indentation that \code{<tab>} generally produces}. 415 414 416 415 \item If the above rules lead to confusing code or to code that's … … 432 431 \end{verbatim} 433 432 434 Following are two examples of breaking an arithmetic expression. The 435 first is preferred, since the break occurs outside the parenthesized 436 expression, which is at a higher level. 433 Following are two examples of breaking an arithmetic expression. The first is 434 preferred, since the break occurs outside the parenthesized expression, which 435 is at a higher level. The second is demonstrating a statement being broken at 436 too low a level. 437 437 438 438 \begin{verbatim} 439 439 $longName1 = $longName2*($longName3 + $longName4 - $longName5) + 440 4*$longname6; 440 4*$longname6; # PREFER 441 441 442 442 $longName1 = $longName2*($longName3 + $longName4 - … … 445 445 446 446 Here are three acceptable ways to format ternary expressions: 447 447 448 \begin{verbatim} 448 449 $alpha = (aLongBooleanExpression) ? $beta : $gamma; … … 506 507 code to make it clearer. 507 508 508 Comments should not be enclosed in large boxes drawn with asterisks or509 othercharacters.509 Comments should not be enclosed in large boxes drawn with hashes or other 510 characters. 510 511 \hfil\break 511 512 Comments should never include special characters such as form-feed and … … 531 532 \subsubsection{Multi-Line Comments} 532 533 533 Merely a repetition of single-line comments. 534 Merely a repetition of single-line comments. Logically distinct but adjoining 535 comments should be separated by an empty comment line. 536 537 \begin{verbatim} 538 # this is the start of a multi-line comment that continues across a couple of 539 # lines then has a logical separation before another comment 540 # 541 # this is an adjoined comment 542 \end{verbatim} 534 543 535 544 \subsubsection{Trailing Comments} … … 607 616 Do not put different types on the same line. Example: 608 617 \begin{verbatim} 609 my ($foo, @fooArray); # WRONG!618 my ($foo, @fooArray); # AVOID! 610 619 \end{verbatim} 611 620 … … 621 630 sub mySubroutine 622 631 { 623 local $count; 632 local $count; # AVOID! 624 633 ... 625 634 } … … 664 673 665 674 \item 666 Closing brace \CODE.}. starts a line by itself indented to match its 667 corresponding opening statement, except when it is a null statement the 668 \CODE.}. should appear immediately after the \CODE.{.. 675 Closing brace \CODE.}. starts a line by itself, except when it is a null 676 statement the \CODE.}. should appear immediately after the \CODE.{.. 669 677 670 678 \item 671 679 The last line before the closing brace must explicitly declare a return value. 680 681 \item 682 683 Do not nest named subroutines. 672 684 \end{itemize} 673 685 … … 695 707 \end{verbatim} 696 708 697 An example of a reasonabl ytwo-statement line is:709 An example of a reasonable two-statement line is: 698 710 \begin{verbatim} 699 711 $foo++; $bar--; … … 713 725 indented to the beginning of the compound statement. 714 726 715 \item Braces are used around all statements, even single statements,716 when they are part of a control structure, such as a \code{if-else} or717 \code{for} statement. This makes it easier to add statements without718 accidentally introducing bugs due to forgetting to add braces.719 \end{itemize}720 721 727 \subsection{return Statements} 722 728 … … 734 740 \end{verbatim} 735 741 736 Note: In absence of an explicit return statement Perl will return the results 737 of the last statement executed. A null \code{return} statement causes the 738 result of the last statement executed to be returned. 739 740 \subsection{if, if-else, if elsif else Statements} 741 742 \code{if} statements must always use braces \{\} around statements and parenthesis 742 Note: In the absence of an explicit return statement Perl will return the 743 results of the last statement executed. A null \code{return} statement also 744 causes the result of the last statement executed to be returned. Relying on 745 this behavior is likely to confuse maintenance programmers and therefore should 746 be avoided. 747 748 \subsection{if, if-else, if-elsif-else Statements} 749 750 \code{if} statements must always use braces \{\} around statements and parentheses 743 751 () around conditionals. 744 752 … … 777 785 778 786 \begin{verbatim} 779 for (my $i = 0; $i < 100; $i++) {787 for (my $i = 0; $i < 100; $i++) { 780 788 print "$i\n"; 781 789 } … … 841 849 \end{verbatim} 842 850 843 \subsection{ label Statements}851 \subsection{Label Statements} 844 852 845 853 Code labels should be indented to align with the previous level of … … 983 991 984 992 Constant names should be in all capital letters and highly descriptive. The 985 \code{constant} pragma should be used to declare constants. Note: 'constants'993 \code{constant} pragma should be used to declare constants. Note: `constants' 986 994 created this way can not be interpolated inside of double quoted strings. 987 995 … … 989 997 \code{use constant PI => 3.14159265;}\hfil\break 990 998 \code{use constant LENGTHS => qw(2, 4, 8);}\hfil\break 991 \code{use constant CLASSES => ( raw => 1, processed=> 2);}\hfil\break999 \code{use constant CLASSES => (a => 1, b => 2);}\hfil\break 992 1000 993 1001 \\ … … 1000 1008 & 1001 1009 1002 \code{package Class::Data::Inheritable;}\hfil\break1003 \code{package Time::HiRes;}\hfil\break1004 \code{package XML::SimpleObject;}\hfil\break1010 \code{package PS::Metadata;}\hfil\break 1011 \code{package PS::Modules::Debias;}\hfil\break 1012 \code{package PS::Modules::FlatField;}\hfil\break 1005 1013 1006 1014 \\ … … 1009 1017 1010 1018 Label names should be in all capital letters and short. Generally they should 1011 attempt to describe the 'thing' being operated on by the loop they are labeling.1019 attempt to describe the `thing' being operated on by the loop they are labeling. 1012 1020 1013 1021 & … … 1098 1106 1099 1107 \begin{verbatim} 1100 if ($a & $b || $c & $d) 1101 if (($a & $b) || ($c & $d)) 1108 if ($a & $b || $c & $d) {} # AVOID! 1109 if (($a & $b) || ($c & $d)) {} # RIGHT 1102 1110 \end{verbatim} 1103 1111 … … 1107 1115 1108 1116 \begin{verbatim} 1109 if (($a == $b && $c == $d) || $e == $f) 1117 if (($a == $b && $c == $d) || $e == $f) {} 1110 1118 $l << ($j + $k) 1111 1119 ($l << $j) + $k
Note:
See TracChangeset
for help on using the changeset viewer.
