Changeset 2591
- Timestamp:
- Dec 1, 2004, 12:34:23 PM (22 years ago)
- Location:
- trunk/doc/misc
- Files:
-
- 6 edited
-
.perltidyrc (modified) (2 diffs)
-
Foo.pm (modified) (3 diffs)
-
Foo.pod (modified) (2 diffs)
-
buildIndex.pl (modified) (8 diffs)
-
foo.pl (modified) (2 diffs)
-
perlCodeConventions.tex (modified) (50 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/misc/.perltidyrc
r2475 r2591 1 # $Id: .perltidyrc,v 1. 5 2004-11-25 02:27:57jhoblitt Exp $1 # $Id: .perltidyrc,v 1.6 2004-12-01 22:34:22 jhoblitt Exp $ 2 2 3 3 # check the syntax with perl … … 14 14 -i=4 15 15 16 # continued statements get no extra indenting16 # continued statements get indented 4 spaces 17 17 -ci=4 18 18 -
trunk/doc/misc/Foo.pm
r2402 r2591 1 # Copyright (C) 2004 Joshua Hoblitt1 # Copyright (C) 2004 Author's Name 2 2 # 3 3 # $Id$ … … 18 18 use constant MAXFOO => 3; # maximum number of foos 19 19 20 my $baz; # is a lexical variable in the top level scope 20 our $bar; # is a package variable 21 22 my $baz; # is a package scoped lexical variable 21 23 22 24 sub fuu … … 28 30 29 31 __END__ 30 31 ... -
trunk/doc/misc/Foo.pod
r2480 r2591 13 13 =head1 DESCRIPTION 14 14 15 More details about what this modules does with Baz.16 17 15 =head1 USAGE 18 16 … … 24 22 =head2 Methods 25 23 24 =head3 Constructors 25 26 =over 4 27 28 =item * new 29 30 =back 31 32 =head3 Object Methods 33 34 =over 4 35 36 =item * foo 37 38 =back 39 26 40 =head3 Class Methods 27 41 28 42 =over 4 29 43 30 =item * methodOne 31 32 details of methodOne 33 34 =item * methodTwo 35 36 details of methodTwo 37 38 ... 44 =item * bar 39 45 40 46 =back 47 48 =head3 Destructors 49 50 =over 4 51 52 =item * DESTROY 53 54 =back 55 56 =head1 DEVELOPER NOTES 57 58 =head2 REFERENCES 41 59 42 60 =head1 CREDITS -
trunk/doc/misc/buildIndex.pl
r2471 r2591 5 5 # $Id: buildIndex.pl,v 1.1 2004/04/20 22:16:17 jhoblitt Exp $ 6 6 7 use 5.008; 8 7 9 use strict; 8 10 use warnings; 9 11 10 use vars qw( $VERSION ); 11 $VERSION = '0.01'; 12 our $VERSION = '0.01'; 12 13 13 14 use File::Basename qw(); … … 21 22 use Pod::Usage qw( pod2usage ); 22 23 23 my ($verbose, $help, $path, $index _dir);24 my ($verbose, $help, $path, $indexDir); 24 25 GetOptions( 25 26 'verbose' => \$verbose, 26 27 'path=s' => \$path, 27 'index=s' => \$index _dir,28 'index=s' => \$indexDir, 28 29 ) 29 30 or pod2usage(2); … … 32 33 pod2usage(-msg => "Required option: --path|-p", -exitval => 2) unless $path; 33 34 34 $index _dir = $path . "/.index" unless defined $index_dir;35 $indexDir = $path . "/.index" unless defined $indexDir; 35 36 36 37 ##my $stripper = HTML::Strip->new; 37 38 38 39 my $writer = Plucene::Index::Writer->new( 39 $index _dir,40 $indexDir, 40 41 Plucene::Plugin::Analyzer::PorterAnalyzer->new(), 41 42 1 # Create the index from scratch … … 44 45 my $doc = Plucene::Document->new; 45 46 46 foreach my $file _name (File::Find::Rule->file->name(qr/^msg\d+\.html/)->in($path)) {47 print "indexing: $file _name\n" if $verbose;48 $writer->add_document(parse _mhonarc_html($file_name));47 foreach my $filename (File::Find::Rule->file->name(qr/^msg\d+\.html/)->in($path)) { 48 print "indexing: $filename\n" if $verbose; 49 $writer->add_document(parseMhonarcHtml($filename)); 49 50 } 50 51 51 sub parse _mhonarc_html52 sub parseMhonarcHtml 52 53 { 53 my $file _name = shift;54 55 my $tree = HTML::TreeBuilder->new_from_file($file _name);54 my $filename = shift; 55 56 my $tree = HTML::TreeBuilder->new_from_file($filename); 56 57 my $doc = Plucene::Document->new; 57 58 58 $doc->add(Plucene::Document::Field->Keyword(file_name => File::Basename::basename($file _name),));59 $doc->add(Plucene::Document::Field->Keyword(file_name => File::Basename::basename($filename),)); 59 60 60 61 # get the header values for to, cc, from, date, and subject 61 62 62 63 # find the <div> tag labeled header 63 my $header _tag = $tree->look_down(_tag => "div", id => "header");64 my $headerTag = $tree->look_down(_tag => "div", id => "header"); 64 65 65 66 my %headers; 66 67 67 foreach my $row _node ($header_tag->look_down(_tag => "tr")) {68 foreach my $rowNode ($headerTag->look_down(_tag => "tr")) { 68 69 69 70 # process each row of the header 70 71 71 72 # get name of header field 72 my $name _node = $row_node->look_down(_tag => "td");73 my $name = lc($name _node->look_down(_tag => "em")->as_text);74 $name _node->delete;73 my $nameNode = $rowNode->look_down(_tag => "td"); 74 my $name = lc($nameNode->look_down(_tag => "em")->as_text); 75 $nameNode->delete; 75 76 76 77 # get content of header field 77 my $content _node = $row_node->look_down(_tag => "td");78 my $content = $content_node->as_text;78 my $contentNode = $rowNode->look_down(_tag => "td"); 79 my $content = $contentNode->as_text; 79 80 80 81 # index "cc" as part of "to" … … 90 91 91 92 # find the <div> tag labeled content 92 my $content _tag = $tree->root->look_down(_tag => "div", id => "content");93 my $contentTag = $tree->root->look_down(_tag => "div", id => "content"); 93 94 94 95 # index message body 95 96 print "\tadding to index content\n" if $verbose; 96 $doc->add(Plucene::Document::Field->UnStored(content => $content _tag->as_text));97 $doc->add(Plucene::Document::Field->UnStored(content => $contentTag->as_text)); 97 98 98 99 return $doc; … … 105 106 =head1 NAME 106 107 107 build _index.pl - generate Plucene/Lucene index of MHonarc archives108 buildIndex.pl - generate Plucene/Lucene index of MHonarc archives 108 109 109 110 =head1 SYNOPSIS 110 111 111 build _index.pl --path dir [--index dir] [--verbose]112 buildIndex.pl --path dir [--index dir] [--verbose] 112 113 113 114 or 114 115 115 build _index.pl -p dir [-i dir] [-v]116 buildIndex.pl -p dir [-i dir] [-v] 116 117 117 118 or 118 119 119 build _index.pl [--help | -h | -? | --version]120 buildIndex.pl [--help | -h | -? | --version] 120 121 121 122 =head1 DESCRIPTION … … 148 149 =back 149 150 150 =head1 DEVELOPER S151 =head1 DEVELOPER NOTES 151 152 152 153 The parser extracts the C<to>, C<cc>, C<from>, C<subject>, and C<date> headers … … 201 202 Place - Suite 330, Boston, MA 02111-1307, USA. 202 203 203 The full text of the license can be found in the L ICENSE file included with204 this module, or in the L<perlgpl> Pod as suppliedwith Perl 5.8.1 and later.204 The full text of the license can be found in the L<perlgpl> Pod as supplied 205 with Perl 5.8.1 and later. 205 206 206 207 =head1 SEE ALSO -
trunk/doc/misc/foo.pl
r2409 r2591 1 1 #!/usr/bin/perl 2 2 3 # Copyright (C) 2004 Joshua Hoblitt3 # Copyright (C) 2004 Author's Name 4 4 # 5 5 # $Id$ … … 25 25 __END__ 26 26 27 ... 27 =pod 28 29 =head1 NAME 30 31 foo.pl - Does something with Baz. 32 33 =head1 SYNOPSIS 34 35 foo.pl --baz 36 37 ... 38 39 =head1 DESCRIPTION 40 41 =head1 OPTIONS 42 43 =over 4 44 45 =item * --baz 46 47 =back 48 49 =head1 DEVELOPER NOTES 50 51 =head1 REFERENCES 52 53 =head1 CREDITS 54 55 Just me, myself, and I. 56 57 =head1 SUPPORT 58 59 Please contact the author directly via e-mail. 60 61 =head1 AUTHOR 62 63 Principle authors and contact info. 64 65 =head1 COPYRIGHT 66 67 Copyright (C) 2004 Author's Name. All rights reserved. 68 69 This program is free software; you can redistribute it and/or modify it under 70 the terms of the GNU General Public License as published by the Free Software 71 Foundation; either version 2 of the License, or (at your option) any later 72 version. 73 74 This program is distributed in the hope that it will be useful, but WITHOUT ANY 75 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 76 PARTICULAR PURPOSE. See the GNU General Public License for more details. 77 78 You should have received a copy of the GNU General Public License along with 79 this program; if not, write to the Free Software Foundation, Inc., 59 Temple 80 Place - Suite 330, Boston, MA 02111-1307, USA. 81 82 The full text of the license can be found in the L<perlgpl> Pod as supplied 83 with Perl 5.8.1 and later. 84 85 =head1 SEE ALSO 86 87 L<Bar::Baz> 88 89 =cut -
trunk/doc/misc/perlCodeConventions.tex
r2541 r2591 1 %%% $Id: perlCodeConventions.tex,v 1.4 1 2004-11-30 22:42:30jhoblitt Exp $1 %%% $Id: perlCodeConventions.tex,v 1.42 2004-12-01 22:34:22 jhoblitt Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 25 25 DR00& 2004-11-12 & First Draft\\ 26 26 \hline 27 DR01& 2004-1 1-24& Second Draft\\27 DR01& 2004-12-01 & Second Draft\\ 28 28 \RevisionsEnd 29 29 … … 46 46 \pagenumbering{arabic} 47 47 48 49 %------------------------------------------------------------------------------ 50 48 51 \section{Introduction} 49 50 52 \subsection{Ancestry} 51 53 … … 60 62 CODE CONVENTIONS FOR THE JAVA^TM PROGRAMMING LANGUAGE. 61 63 Copyright 1995-1999 Sun 62 Microsys ytems, Inc. All rights reserved.64 Microsystems, Inc. All rights reserved. 63 65 \end{verbatim} 64 66 … … 87 89 \subsection{Conformance} 88 90 89 If any of the conventions est iblished in this document conflict with source91 If any of the conventions established in this document conflict with source 90 92 code that has been formated by \code{perltidy} (see \S\ref{perltidy}), the 91 93 formatting as output by \code{perltidy} will be considered to be in compliance … … 98 100 99 101 \code{<rhl@astro.princeton.edu>}. 102 100 103 101 104 %------------------------------------------------------------------------------ … … 126 129 \hline 127 130 \file{Makefile.PL}& 128 The preferred name for the file that calls \code{ExtUtils::MakeMaker} or 129 \code{Module::Build} to create the makefile for Swig generated C code.\\ 131 The preferred name for the file that invokes a ``build'' process. Typically 132 this calls \code{ExtUtils::MakeMaker} or \code{Module::Build} setup the the 133 necessary files to install a module or compile Swig generated C code.\\ 130 134 \end{tabular} 131 135 \end{center} … … 136 140 \section{File Organization} 137 141 142 General rules: 143 144 \begin{itemize} 145 \item 138 146 A file consists of sections that should be separated by blank lines 139 147 and an optional comment identifying each section. 140 148 149 \item 141 150 Files longer than 1000 lines are cumbersome and should be avoided. 142 151 152 \item 143 153 For an example of a properly formatted program, see 144 Source File Example (\S\ref{SourceExample}). 145 154 Complete Program Example (\S\ref{SourceExample}). 155 156 \item 146 157 ``Scripts'' have user documentation included at the end of the file. 147 158 159 \item 148 160 ``Modules'' have documentation included in a companion \code{.pod}. 161 \end{itemize} 149 162 150 163 \subsection{Source Files} 151 152 164 \subsubsection{Perl Scripts} 153 165 … … 156 168 \begin{itemize} 157 169 \item 158 A Bourne shell ``she-bang'' for perl. \code{#!/usr/bin/perl}.170 A Bourne shell ``she-bang'' for \code{perl}. \code{#!/usr/bin/perl}. 159 171 160 172 \item … … 163 175 164 176 \item 165 An optional minimum perl version requirement in long form (vStrings are not166 allowed). Where \code(requirement = revision + version / 1000 + subversion / 167 1\_000\_000). E.g. A minimum requirement of Perl 5.8.5 would be expressed as 168 \code{use 5.008005}177 An optional minimum \code{perl} version requirement in long form (vStrings are 178 not allowed). Where \code(requirement = revision + version / 1000 + subversion 179 / 1\_000\_000). e.g. A minimum requirement of \code{perl} 5.8.5 would be 180 expressed as \code{use 5.008005} 169 181 170 182 \item … … 182 194 183 195 \item 184 Any script level "globals" declared as lexical variables. E.g. \code{my $foo}196 Any script level "globals" declared as lexical variables. e.g. \code{my $foo} 185 197 186 198 \item … … 188 200 189 201 \item 190 A \code{__END__} token to instruct the perlparser to stop looking for202 A \code{__END__} token to instruct the \code{perl} parser to stop looking for 191 203 executable code. 192 204 … … 195 207 \end{itemize} 196 208 197 e.g. for file \file{foo.pl}: 198 199 \verbatiminput{foo.pl} 209 For an example of a properly organized script, see Script File Example 210 (\S\ref{foo.pl}). 200 211 201 212 \subsubsection{Perl Modules} 202 213 203 Perl Module/Namespaces deviate slightly from the standard naming conventions in 204 that the first character is always capitalized. All Pan-STARRS specific 205 modules should be under the top level \code{PS::} namespace. 214 Module files should have the following order: 206 215 207 216 \begin{itemize} … … 214 223 215 224 \item 216 An optional minimum perl version requirement in long form (vStrings are not allowed).217 Where \code(requirement = revision + version / 1000 + subversion / 1\_000\_000). 218 E.g. A minimum requirement of Perl 5.8.5 would be expressed as \code{use219 5.008005}225 An optional minimum \code{perl} version requirement in long form (vStrings are 226 not allowed). Where \code(requirement = revision + version / 1000 + subversion 227 / 1\_000\_000). e.g. A minimum requirement of \code{perl} 5.8.5 would be 228 expressed as \code{use 5.008005} 220 229 221 230 \item … … 235 244 236 245 \item 237 Any script level ``globals'' declared as lexical variables. E.g. \code{my 238 $foo} 246 Any package variables. e.g. \code{our $foo} 247 248 \item 249 Any package scoped lexical variables. e.g. \code{my $foo} 239 250 240 251 \item … … 248 259 A \code{__END__} token to instruct the perl parser to stop looking for 249 260 executable code. 261 250 262 \end{itemize} 251 263 252 e.g. for file \file{Foo.pm}: 253 254 \verbatiminput{Foo.pm} 264 For an example of a properly organized module, see Module File Example 265 (\S\ref{Foo.pm}). 255 266 256 267 \subsubsection{Plain Old Documentation} 257 268 \label{pod} 258 269 259 This is the format for documentation in a \code{.pl} file after the 260 \code{__END__} token and the \code{.pod} file that should accompany a module 261 (\code{.pm}). 262 263 e.g. for file Foo.pod: 264 265 \verbatiminput{Foo.pod} 270 This is the format for documentation in a \code{.pod} file that should 271 accompany a module. 272 273 For an example of a properly organized Pod, see Pod File Example 274 (\S\ref{Foo.pod}). 275 266 276 267 277 %------------------------------------------------------------------------------ … … 269 279 \section{Indentation} 270 280 271 Four spaces should be used as the unit of indentation. Spaces are 272 recommended over tabs for indentation, but if tabs are used, the tabs 273 stops must be set to 8 spaces, not 4. 281 Four spaces should be used as the unit of indentation; tabs are forbidden. 274 282 275 283 \subsection{Line Length} … … 367 375 When deactivating 3 or more lines of code an \code{if} statement should be used 368 376 with a false boolean value. The opening and closing of the \code{if} statement 369 should be nest to the same depth as the surrounding code and the deactivated377 should be nested to the same depth as the surrounding code and the deactivated 370 378 section should be indented. 371 379 … … 380 388 \end{verbatim} 381 389 382 Comments should be used to give overviews of code and provide 383 additional information that is not readily available in the code 384 itself. Comments should contain only information that is relevant to 385 reading and understanding the program. For example, information about 386 how the corresponding package is built or in what directory it resides 387 should not be included as a comment. 388 389 Discussion of nontrivial or non-obvious design decisions is 390 appropriate, but avoid duplicating information that is present in (and 391 clear from) the code. It is too easy for redundant comments to get out 392 of date. In general, avoid any comments that are likely to get out of 393 date as the code evolves. 394 395 Note: The frequency of comments sometimes reflects poor quality of 396 code. When you feel compelled to add a comment, consider rewriting the 397 code to make it clearer. 398 390 \subsection{Implementation Comments} 391 392 General rules: 393 394 \begin{itemize} 395 \item 396 Comments should be used to give overviews of code and provide additional 397 information that is not readily available in the code itself. Comments should 398 contain only information that is relevant to reading and understanding the 399 program. For example, information about how the corresponding package is built 400 or in what directory it resides should not be included as a comment. 401 402 \item 403 Discussion of nontrivial or non-obvious design decisions is appropriate, but 404 avoid duplicating information that is present in (and clear from) the code. It 405 is too easy for redundant comments to get out of date. In general, avoid any 406 comments that are likely to get out of date as the code evolves. 407 408 \item 399 409 Comments should not be enclosed in large boxes drawn with hashes or other 400 410 characters. 401 \hfil\break 411 412 \item 402 413 Comments should never include special characters such as form-feed and 403 414 backspace. 404 405 \subsection{Implementation Comment Formats} 415 \end{itemize} 416 417 \emph{The frequency of comments sometimes reflects poor quality of code. When 418 you feel compelled to add a comment, consider rewriting the code to make it 419 clearer.} 406 420 407 421 Programs can have three styles of implementation comments: single-line, … … 455 469 additional spaces to cause trailing comments in adjoining lines to be 456 470 vertically aligned. Until such time as \code{perltidy} can following this 457 convention or a replacement tool is located, codeas formatted by471 convention or a replacement tool is located, trailing comments as formatted by 458 472 \code{perltidy} will be considered acceptable.} 459 473 460 474 \subsection{API Comments} 461 \label{DocComments}462 475 463 476 Plain Old Documentation format or Pod will be used to produce documentation of … … 496 509 \begin{verbatim} 497 510 my ($verbose, $help); # Correct when the meaning is clear 511 my ($foo, $bar) = @_; # Correct in a subroutine 498 512 \end{verbatim} 499 513 … … 502 516 \begin{verbatim} 503 517 my ($foo, @fooArray); # AVOID! 518 \end{verbatim} 519 520 \subsubsection{Scalars} 521 522 Do not initialize more then one scalar per declaration. 523 524 \begin{verbatim} 525 my $foo = \$bar; # Correct 526 my ($foo, $bar) = (1, 2); # AVOID! 527 \end{verbatim} 528 529 \subsubsection{Arrays} 530 531 When assigning a large number of elements to an array a single column table 532 format should be used. 533 534 \begin{verbatim} 535 my @foo = (1, 'two', 3); # Correct 536 537 my @foo = ( # Correct 538 1, 539 'two', 540 3, 541 'four', 542 5, 543 'six', 544 7, 545 'eight', 546 9, 547 'ten' 548 ); 549 550 my @foo = (1, 'two', 3, 'four', 5, 'six', ... # AVOID! 551 \end{verbatim} 552 553 Consider using the \code{qw} operator when assigning strings to an array. 554 555 \begin{verbatim} 556 my @foo = qw( 1 two 3 ); 557 558 my @foo = qw( 559 1 560 two 561 3 562 four 563 5 564 six 565 ); 566 \end{verbatim} 567 568 \subsubsection{Hashes} 569 570 When assigning a large number of elements to a hash a double column table 571 format should be used. 572 573 \begin{verbatim} 574 my %foo = (one => 1, two => 2); # Correct 575 576 my %foo = ( # Correct 577 one => 1, 578 two => 2, 579 three => 3, 580 four => 4, 581 five => 5, 582 six => 6, 583 seven => 7, 584 eight => 8, 585 nine => 9, 586 ten => 10 587 ); 588 589 my %foo = (one => 1, two => 2, three => 3, ... # AVOID! 504 590 \end{verbatim} 505 591 … … 520 606 \end{verbatim} 521 607 522 Note: This restriction does not apply to Perl's built in variables. 608 \emph{This restriction does not apply to Perl's built in variables.} 609 610 \subsection{Package Variables} 611 612 See When to Make Symbols Global (\S\ref{globals}). 523 613 524 614 \subsection{Initialization} 525 615 616 General rules: 617 618 \begin{itemize} 619 \item 526 620 Try to initialize local variables where they're declared. 527 621 622 \item 528 623 Do not initialize variables with an empty string or list - this is pointless. 529 624 625 \item 530 626 A reason not to initialize a variable where it's declared is if the initial 531 627 value depends on some computation occurring first. 532 628 533 In some cases it may be necessary to initialize a variable to suppress 534 a compiler warning; in this case a comment should explain the circumstances. 629 \item 630 In some cases it may be necessary to initialize a variable to suppress a 631 compiler warning; in this case a comment should explain the circumstances. 632 \end{itemize} 535 633 536 634 \subsection{Placement} … … 543 641 \subsection{Subroutine Declarations} 544 642 545 When coding Perlsubroutines the following formatting rules should be643 When coding subroutines the following formatting rules should be 546 644 followed: 547 645 … … 558 656 \item 559 657 The first line after the opening brace should declare a list of lexical 560 variables for input parameters and assign \code{ @_} to it.658 variables for input parameters and assign \code{shift} or \code{@_} to it. 561 659 562 660 \item … … 568 666 569 667 \item 570 668 Do not directly use the \code{@_} array. 669 670 \item 571 671 Do not nest named subroutines. 572 672 \end{itemize} 573 673 574 674 \begin{verbatim} 575 sub subName 675 sub subName # Correct 676 { 677 my $param = shift; 678 ... 679 return $val; 680 } 681 682 sub subName # Correct 576 683 { 577 684 my ($param1, $param2, ...) = @_; 578 685 ... 579 580 686 return $val; 687 } 688 689 sub subName # AVOID! 690 { 691 if ($_[0] eq "foo") { 692 ... 581 693 } 582 694 \end{verbatim} … … 626 738 return undef; # Correct 627 739 return; # AVOID! 628 629 return $myDisk->size; 630 631 return ($size ? $size : $defaultSize); 632 \end{verbatim} 633 634 Note: In the absence of an explicit return statement Perl will return the 740 return $myDisk->size; # Correct 741 return ($size ? $size : $defaultSize); # Correct 742 \end{verbatim} 743 744 \emph{In the absence of an explicit return statement Perl will return the 635 745 results of the last statement executed. A null \code{return} statement also 636 746 causes the result of the last statement executed to be returned. Relying on 637 747 this behavior is likely to confuse maintenance programmers and therefore should 638 be avoided. 748 be avoided.} 639 749 640 750 \subsection{if, if-else, if-elsif-else Statements} … … 766 876 Two blank lines should always be used in the following circumstances: 767 877 \begin{itemize} 768 \item Between sections of a source file 878 \item 879 Between sections of a source file 769 880 \end{itemize} 770 881 … … 772 883 773 884 \begin{itemize} 774 \item Between the local variables in a subroutine and its first statement 775 776 \item Between logical sections inside a subroutine to improve readability 885 \item 886 Between the local variables in a subroutine and its first statement 887 888 \item 889 Between logical sections inside a subroutine to improve readability 777 890 \end{itemize} 778 891 … … 790 903 \end{verbatim} 791 904 792 Note that a blank space should not be used between a subroutine name and its 793 opening parenthesis. This helps to distinguish keywords from subroutine calls. 794 795 \item 796 A blank space should appear after commas in argument lists. 905 \emph{A blank space should not be used between a subroutine name and its 906 opening parenthesis. This helps to distinguish keywords from subroutine calls.} 907 908 \item 909 A blank space should appear after commas in parameter lists. 910 911 \begin{verbatim} 912 subName(1, 2, 3); 913 \end{verbatim} 797 914 798 915 \item … … 828 945 \end{itemize} 829 946 947 Blank spaces should \textit{not} be used in the following circumstances: 948 949 \begin{itemize} 950 \item 951 A dereferencing or method call should not have any blank spaces around the 952 \code{->} operator. 953 954 \begin{verbatim} 955 $myHashRef->{'foo'}; 956 $myObject->foo; 957 \end{verbatim} 958 959 \end{itemize} 830 960 %------------------------------------------------------------------------------ 831 961 … … 843 973 \textbf{Rules for Naming} & 844 974 \textbf{Examples} \\ 975 \hline\\ 976 977 Script Files & 978 979 The filenames of all scripts should be verbal phrases, in mixed case. The 980 capitalized \code{.PL} suffix is reserved for ``build'' scripts. 981 982 & 983 984 \code{foo.pl}\hfil\break 985 \code{fooBar.pl}\hfil\break 986 \code{Makefile.PL}\hfil\break 987 988 \\ 989 990 Module Files & 991 992 The filenames of all modules should be verbal phrases, in mixed case, with the 993 first letter capitalized. 994 995 & 996 997 \code{Foo.pm}\hfil\break 998 \code{FooBar.pm}\hfil\break 999 1000 \\ 1001 1002 Pod Files & 1003 1004 The filenames of all stand-alone Pod should follow the same rules as module 1005 files. 1006 1007 & 1008 1009 \code{Foo.pod}\hfil\break 1010 \code{FooBar.pod}\hfil\break 1011 1012 \\ 845 1013 846 1014 Subroutines & … … 873 1041 874 1042 \code{$i;}\hfil\break 1043 \code{$i;}\hfil\break 875 1044 \code{$c;}\hfil\break 876 1045 \code{$myWidth;}\hfil\break 877 \hfil\break878 1046 \code{$pseudo;}\hfil\break 879 1047 \code{$myFiddleFactor;}\hfil\break … … 884 1052 885 1053 Constant names should be in all capital letters and highly descriptive. The 886 \code{constant} pragma should be used to declare constants. Note: `constants' 887 created this way can not be interpolated inside of double quoted strings. 1054 \code{constant} pragma should be used to declare constants. 1055 \emph{``constants'' created this way can not be interpolated inside of double 1056 quoted strings.} 888 1057 889 1058 & 890 1059 \code{use constant PI => 3.14159265;}\hfil\break 891 \code{use constant LENGTHS => qw( 2, 4, 8);}\hfil\break892 \code{use constant CLASSES => (a => 1, b => 2);}\hfil\break1060 \code{use constant LENGTHS => qw( 2, 4, 8 );}\hfil\break 1061 \code{use constant CLASSES => {a => 1, b => 2};}\hfil\break 893 1062 894 1063 \\ … … 901 1070 & 902 1071 903 \code{package PS::Metadata;}\hfil\break 904 \code{package PS::Modules::Debias;}\hfil\break 905 \code{package PS::Modules::FlatField;}\hfil\break 1072 \code{package PS::IPP::Metadata;}\hfil\break 1073 \code{package PS::IPP::Modules::Debias;}\hfil\break 1074 \code{package PS::MOPS::DB::Detections;}\hfil\break 1075 \code{package PS::MOPS::Util::MPC;}\hfil\break 906 1076 907 1077 \\ … … 929 1099 930 1100 \subsection{When to Make Symbols Global} 1101 \label{globals} 931 1102 932 1103 Only declare variables as package variables (\code{our}) if they are intended … … 936 1107 \begin{verbatim} 937 1108 our $VERSION = '1.00'; # Correct 1109 our $localCounter; # AVOID! - should be lexical 938 1110 939 1111 use base qw( Exporter ); 940 941 1112 our @EXPORT_OK = qw( $foo $bar ); # Correct 942 943 our $localCounter; # AVOID!944 1113 \end{verbatim} 945 1114 … … 1079 1248 \subsubsection{FileHandles} 1080 1249 1081 Do n't use ``bare-words'' as filehandles except for \code{STDIN}, \code{STDOUT},1250 Do not use ``bare-words'' as filehandles except for \code{STDIN}, \code{STDOUT}, 1082 1251 and \code{STDERR}. 1083 1252 … … 1085 1254 open(STDOUT, '>', $foo) or die "can not open STDOUT: $!"; # Correct 1086 1255 open(my $fh, '>', $foo) or die "can not open file $foo: $!"; # Correct 1087 open(FILE , '>', $foo) or die "can not open file $foo: $!";# AVOID!1256 open(FILE, '>', $foo) or die "can not open file $foo: $!"; # AVOID! 1088 1257 \end{verbatim} 1089 1258 … … 1100 1269 \subsubsection{Chop vs. Chomp} 1101 1270 1102 Do n't use \code{chop} to remove newline characters as it will remove any1271 Do not use \code{chop} to remove newline characters as it will remove any 1103 1272 character (newline or not). 1104 1273 1105 1274 \begin{verbatim} 1106 1275 my $foo = "baz\n"; # string with newline 1107 1108 1276 chomp($foo); # removes "\n" - Correct 1109 1277 chomp($foo); # chomping the same string twice is safe 1110 1111 1278 chop($foo); # removes "z" - AVOID! 1112 1279 \end{verbatim} … … 1125 1292 1126 1293 Use ``cuddled'' brackets \CODE.{}. when accessing a hash element. It is 1127 acceptable to use ``bare-words'' as a hash key ( Note:this rule may be subject1128 to change ).1294 acceptable to use ``bare-words'' as a hash key (\emph{this rule may be subject 1295 to change}). 1129 1296 1130 1297 \begin{verbatim} … … 1147 1314 \end{verbatim} 1148 1315 1149 Do n't use \code{require} to prevent a module from exporting symbols into the1316 Do not use \code{require} to prevent a module from exporting symbols into the 1150 1317 caller's namespace. Instead, provide \code{use} with an empty parameter list. 1151 1318 … … 1164 1331 \subsubsection{Inheritance} 1165 1332 1166 Do n't use the \code{@ISA} package variable for subclassing. Instead, use the1333 Do not use the \code{@ISA} package variable for subclassing. Instead, use the 1167 1334 \code{base} pragma. 1168 1335 … … 1177 1344 ``bare-word''. Instead, use empty parentheses adjoined to the subroutine call. 1178 1345 1179 \ code{subs} pragma is a last resort.1346 \emph{Only use the \code{subs} pragma as a last resort.} 1180 1347 1181 1348 \begin{verbatim} … … 1187 1354 \end{verbatim} 1188 1355 1356 \subsubsection{Calling Methods} 1357 1358 Leave the parentheses off method calls that aren't being passed parameters. 1359 1360 \begin{verbatim} 1361 $myObj->fooBar; # Correct 1362 $myObj->fooBar($foo); # Correct 1363 $myObj->fooBar(); # AVOID! 1364 \end{verbatim} 1365 1366 \subsubsection{Quoting Strings} 1367 1368 \begin{itemize} 1369 \item 1370 Unless variable interpolation needs to occur inside of a string or is likely to 1371 be needed in the future, use single quotes \code{''} instead of double quotes 1372 \code{""}. 1373 1374 \item 1375 When possible use \code{END} as the termination token for ``\code{<<HERE} 1376 docs''. 1377 1378 \begin{verbatim} 1379 my $string = <<END 1380 foo bar 1381 bat baz 1382 END 1383 \end{verbatim} 1384 1385 \item 1386 Try to use the \code{qw} operator whenever possible. 1387 1388 \item 1389 Consider using the \code{q} and \code{qq} operators instead of backslashes 1390 (\code{\}) when quoting strings that contain other quotes or blackslases. 1391 1392 \item 1393 Consider using the \code{quotemeta} subroutine when handling strings that 1394 contain meta-characters. 1395 \end{itemize} 1396 1397 \subsubsection{String Concatenation} 1398 1399 Avoid use of the string concatenation operator (\code{.}) where it's 1400 unnecessary. 1401 1402 \begin{verbatim} 1403 $foo = "foo" . "bar"; # Correct 1404 $foo .= "bar"; # Correct 1405 print "foo" , "bar"; # Correct 1406 print "foo" . "bar"; # AVOID! 1407 \end{verbatim} 1408 1409 \subsubsection{Regular Expressions} 1410 1411 Use the ``extended'' regular expression syntax whenever practical. 1412 1413 \begin{verbatim} 1414 qr/^ # Correct 1415 ( -? (?:Bork\s*){0,9} , (?:Bork\s*){0,9} 1416 , (?:Bork\s*){0,9} , (?:Bork\s*){0,9} ) 1417 - ( (?:Bork\s*){0,9} , (?:Bork\s*){0,9} ) 1418 - ( (?:Bork\s*){0,9} , (?:Bork\s*){0,9} ) 1419 T ( (?:Bork\s*){0,9} , (?:Bork\s*){0,9} ) 1420 : ( (?:Bork\s*){0,9} , (?:Bork\s*){0,9} ) 1421 : ( (?:Bork\s*){0,9} , (?:Bork\s*){0,9} ) 1422 $/ix; 1423 1424 qr/^(-?(?:Bork\s*){0,9},(?:Bork\s*){0,9},(?:Bork\s*){0,9},...$/i # AVOID! 1425 \end{verbatim} 1426 1189 1427 \subsubsection{Subroutine Prototypes} 1190 1428 … … 1202 1440 1203 1441 \section{Code Examples} 1204 \subsection{Source File Example} 1442 \subsection{Script File Example} 1443 \label{foo.pl} 1444 1445 \verbatiminput{foo.pl} 1446 1447 \subsection{Module File Example} 1448 \label{Foo.pm} 1449 1450 \verbatiminput{Foo.pm} 1451 1452 \subsection{Pod File Example} 1453 \label{Foo.pod} 1454 1455 \verbatiminput{Foo.pod} 1456 1457 \subsection{Complete Program Example} 1205 1458 \label{SourceExample} 1206 1459 … … 1209 1462 1210 1463 \verbatiminput{buildIndex.pl} 1464 1211 1465 1212 1466 %------------------------------------------------------------------------------ … … 1228 1482 \verbatiminput{.perltidyrc} 1229 1483 1484 1485 %------------------------------------------------------------------------------ 1486 1230 1487 \section{Params::Validate} 1231 1488 \label{Params::Validate} … … 1241 1498 1242 1499 An example \code{Params::Validate} named parameters validation spec taken from 1243 the \code{DateTime} module. 1244 1245 \begin{verbatim} 1246 my $BasicValidate = 1247 { year => { type => SCALAR }, 1248 month => { type => SCALAR, default => 1, 1249 callbacks => 1250 { 'is between 1 and 12' => 1251 sub { $_[0] >= 1 && $_[0] <= 12 } 1252 }, 1253 }, 1254 day => { type => SCALAR, default => 1, 1255 callbacks => 1256 { 'is a possible valid day of month' => 1257 sub { $_[0] >= 1 && $_[0] <= 31 } 1258 }, 1259 }, 1260 hour => { type => SCALAR, default => 0, 1261 callbacks => 1262 { 'is between 0 and 23' => 1263 sub { $_[0] >= 0 && $_[0] <= 23 }, 1264 }, 1265 }, 1266 minute => { type => SCALAR, default => 0, 1267 callbacks => 1268 { 'is between 0 and 59' => 1269 sub { $_[0] >= 0 && $_[0] <= 59 }, 1270 }, 1271 }, 1272 second => { type => SCALAR, default => 0, 1273 callbacks => 1274 { 'is between 0 and 61' => 1275 sub { $_[0] >= 0 && $_[0] <= 61 }, 1276 }, 1277 }, 1278 nanosecond => { type => SCALAR, default => 0, 1279 callbacks => 1280 { 'cannot be negative' => 1281 sub { $_[0] >= 0 }, 1282 } 1283 }, 1284 locale => { type => SCALAR | OBJECT, 1285 default => undef }, 1286 language => { type => SCALAR | OBJECT, 1287 optional => 1 }, 1288 }; 1289 \end{verbatim} 1290 1291 An example of how a validation spec is used in the \code{DateTime} module. 1292 1293 \begin{verbatim} 1294 use Params::Validate qw( validate validate_pos SCALAR BOOLEAN HASHREF OBJECT ); 1295 . 1296 . 1297 1298 sub new 1299 { 1300 my $class = shift; 1301 my %p = validate( @_, $NewValidate ); 1302 . 1303 . 1500 the \code{HTTP::Range}\footnote{HTTP::Range - 1501 http://search.cpan.org/~jhoblitt/HTTP-Range/} module. 1502 1503 \begin{verbatim} 1504 my %args = validate( @_, 1505 { 1506 request => { 1507 type => OBJECT, 1508 isa => 'HTTP::Request', 1509 }, 1510 length => { 1511 type => SCALAR, 1512 callbacks => { 1513 'length is > 0' => sub { $_[0] > 0 }, 1514 'length is + integer' => sub { $_[0] =~ /^\d+$/ }, 1515 }, 1516 }, 1517 segments => { 1518 type => SCALAR, 1519 default => 4, 1520 callbacks => { 1521 'segments is > 1' => sub { $_[0] > 1 }, 1522 'segments is + integer' => sub { $_[0] =~ /^\d+$/ }, 1523 'segments is <= length' => sub { $_[0] <= $_[1]->{ 'length' } }, 1524 }, 1525 }, 1526 }, 1527 ); 1528 1304 1529 \end{verbatim} 1305 1530 … … 1308 1533 further details. 1309 1534 1535 1536 %------------------------------------------------------------------------------ 1537 1310 1538 \bibliographystyle{plain} 1311 1539 \bibliography{panstarrs}
Note:
See TracChangeset
for help on using the changeset viewer.
