Index: /tags/rel-DR01/doc/misc/.perltidyrc =================================================================== --- /tags/rel-DR01/doc/misc/.perltidyrc (revision 2595) +++ /tags/rel-DR01/doc/misc/.perltidyrc (revision 2595) @@ -0,0 +1,52 @@ +# $Id: .perltidyrc,v 1.6 2004-12-01 22:34:22 jhoblitt Exp $ + +# check the syntax with perl +-syn +-pscf=-wc + +# enable perltiday warnings +-w + +# use only \n as a line ending +-ole=unix + +# indent 4 spaces +-i=4 + +# continued statements get indented 4 spaces +-ci=4 + +# maximum line length +-l=110 + +# edit in place but backup the file first +-b + +# cuddled elses +-ce + +# Cish tight containers +-bt=2 +-pt=2 +-sbt=2 + +# place the brace on the right after a multi-line expression +-bar + +# don't indent closing tokens +-cti=0 + +# no spaces before semicolons in Cish for loops +-nsfs + +# no outdenting long lines +-noll + +# don't outdent labels +-nola + +# treat ## as commented code and not a comment +-sbc + +# opening sub brace on a new line +-sbl Index: /tags/rel-DR01/doc/misc/Foo.pm =================================================================== --- /tags/rel-DR01/doc/misc/Foo.pm (revision 2595) +++ /tags/rel-DR01/doc/misc/Foo.pm (revision 2595) @@ -0,0 +1,31 @@ +# Copyright (C) 2004 Author's Name +# +# $Id$ + +package Foo; + +use 5.008005; # optional + +use strict; # not optional +use warnings; # not optional + +our $VERSION = '0.01'; # this is version 0.01 + +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 + +our $bar; # is a package variable + +my $baz; # is a package scoped lexical variable + +sub fuu +{ + +} + +1; + +__END__ Index: /tags/rel-DR01/doc/misc/Foo.pod =================================================================== --- /tags/rel-DR01/doc/misc/Foo.pod (revision 2595) +++ /tags/rel-DR01/doc/misc/Foo.pod (revision 2595) @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +Foo - Does something with Baz. + +=head1 SYNOPSIS + + use Foo; + + ... + +=head1 DESCRIPTION + +=head1 USAGE + +=head2 Import Parameters + +This module accepts no arguments to it's C method and exports no +I. + +=head2 Methods + +=head3 Constructors + +=over 4 + +=item * new + +=back + +=head3 Object Methods + +=over 4 + +=item * foo + +=back + +=head3 Class Methods + +=over 4 + +=item * bar + +=back + +=head3 Destructors + +=over 4 + +=item * DESTROY + +=back + +=head1 DEVELOPER NOTES + +=head2 REFERENCES + +=head1 CREDITS + +Just me, myself, and I. + +=head1 SUPPORT + +Where to get help. + +=head1 AUTHOR + +Principle authors and contact info. + +=head1 COPYRIGHT + +Copyright (C) 2004 Author's Name. 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 Index: /tags/rel-DR01/doc/misc/buildIndex.pl =================================================================== --- /tags/rel-DR01/doc/misc/buildIndex.pl (revision 2595) +++ /tags/rel-DR01/doc/misc/buildIndex.pl (revision 2595) @@ -0,0 +1,212 @@ +#!/usr/bin/perl + +# Copyright (C) 2004 Joshua Hoblitt +# +# $Id: buildIndex.pl,v 1.1 2004/04/20 22:16:17 jhoblitt Exp $ + +use 5.008; + +use strict; +use warnings; + +our $VERSION = '0.01'; + +use File::Basename qw(); +use File::Find::Rule; +##use HTML::Strip; +use HTML::TreeBuilder; +use Plucene::Index::Writer; +use Plucene::Plugin::Analyzer::PorterAnalyzer; + +use Getopt::Long qw( GetOptions :config auto_help auto_version ); +use Pod::Usage qw( pod2usage ); + +my ($verbose, $help, $path, $indexDir); +GetOptions( + 'verbose' => \$verbose, + 'path=s' => \$path, + 'index=s' => \$indexDir, + ) + or pod2usage(2); + +pod2usage(-msg => "Unknown option: @ARGV", -exitval => 2) if @ARGV; +pod2usage(-msg => "Required option: --path|-p", -exitval => 2) unless $path; + +$indexDir = $path . "/.index" unless defined $indexDir; + +##my $stripper = HTML::Strip->new; + +my $writer = Plucene::Index::Writer->new( + $indexDir, + Plucene::Plugin::Analyzer::PorterAnalyzer->new(), + 1 # Create the index from scratch +); + +my $doc = Plucene::Document->new; + +foreach my $filename (File::Find::Rule->file->name(qr/^msg\d+\.html/)->in($path)) { + print "indexing: $filename\n" if $verbose; + $writer->add_document(parseMhonarcHtml($filename)); +} + +sub parseMhonarcHtml +{ + my $filename = shift; + + my $tree = HTML::TreeBuilder->new_from_file($filename); + my $doc = Plucene::Document->new; + + $doc->add(Plucene::Document::Field->Keyword(file_name => File::Basename::basename($filename),)); + + # get the header values for to, cc, from, date, and subject + + # find the
tag labeled header + my $headerTag = $tree->look_down(_tag => "div", id => "header"); + + my %headers; + + foreach my $rowNode ($headerTag->look_down(_tag => "tr")) { + + # process each row of the header + + # get name of header field + my $nameNode = $rowNode->look_down(_tag => "td"); + my $name = lc($nameNode->look_down(_tag => "em")->as_text); + $nameNode->delete; + + # get content of header field + my $contentNode = $rowNode->look_down(_tag => "td"); + my $content = $contentNode->as_text; + + # index "cc" as part of "to" + $name =~ s/^cc/to/; + + # index header fields + if ($name =~ /^(to|from|subject|date)/i) { + ##$content = $stripper->parse( $content ); + print "\tadding to index $name: $content\n" if $verbose; + $doc->add(Plucene::Document::Field->Text($name => $content)); + } + } + + # find the
tag labeled content + my $contentTag = $tree->root->look_down(_tag => "div", id => "content"); + + # index message body + print "\tadding to index content\n" if $verbose; + $doc->add(Plucene::Document::Field->UnStored(content => $contentTag->as_text)); + + return $doc; +} + +__END__ + +=pod + +=head1 NAME + +buildIndex.pl - generate Plucene/Lucene index of MHonarc archives + +=head1 SYNOPSIS + + buildIndex.pl --path dir [--index dir] [--verbose] + + or + + buildIndex.pl -p dir [-i dir] [-v] + + or + + buildIndex.pl [--help | -h | -? | --version] + +=head1 DESCRIPTION + +Parses directories of MHonarc generated HTML files and builds a searchable +index. The parser requires the HTML files to be in a specifc format which is +signifigantly modified from default MHonarc format. The indexer creates a +directory of index files in the Plucene/Lucene format. + +=head1 OPTIONS + +=over 4 + +=item * --path dir | -p dir + +Directory of MHonarc generated HTML files to process. + +=item * --index dir | -i dir + +Directory to write the Plucene/Lucene index files to. Defaults to C<--path> + '.index'. + +=item * --verbose | -v + +Print status information while processing. + +=item * --help | -h | -? + +=item * --version + +=back + +=head1 DEVELOPER NOTES + +The parser extracts the C, C, C, C, and C headers +along with the message body. The HTML document is required to contain tags in +this format. + + + +
+ [ message body ] +
+ +The parser is insenstive to the ordering of the C
and C +CdivE> tags. All other tags in the document are ignored. + +=head1 CREDITS + +Just me, myself, and I. + +=head1 SUPPORT + +Please contact the author directly via e-mail. + +=head1 AUTHOR + +Joshua Hoblitt + +=head1 COPYRIGHT + +Copyright (C) 2004 Joshua Hoblitt. 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 L Pod as supplied +with Perl 5.8.1 and later. + +=head1 SEE ALSO + +L, +L + +=cut Index: /tags/rel-DR01/doc/misc/foo.pl =================================================================== --- /tags/rel-DR01/doc/misc/foo.pl (revision 2595) +++ /tags/rel-DR01/doc/misc/foo.pl (revision 2595) @@ -0,0 +1,89 @@ +#!/usr/bin/perl + +# Copyright (C) 2004 Author's Name +# +# $Id$ + +use 5.008005; # optional + +use strict; # not optional +use warnings; # not optional + +our $VERSION = '0.01'; # optional - handy with Getopt::Long + +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__ + +=pod + +=head1 NAME + +foo.pl - Does something with Baz. + +=head1 SYNOPSIS + + foo.pl --baz + + ... + +=head1 DESCRIPTION + +=head1 OPTIONS + +=over 4 + +=item * --baz + +=back + +=head1 DEVELOPER NOTES + +=head1 REFERENCES + +=head1 CREDITS + +Just me, myself, and I. + +=head1 SUPPORT + +Please contact the author directly via e-mail. + +=head1 AUTHOR + +Principle authors and contact info. + +=head1 COPYRIGHT + +Copyright (C) 2004 Author's Name. 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 L Pod as supplied +with Perl 5.8.1 and later. + +=head1 SEE ALSO + +L + +=cut Index: /tags/rel-DR01/doc/misc/perlCodeConventions.tex =================================================================== --- /tags/rel-DR01/doc/misc/perlCodeConventions.tex (revision 2595) +++ /tags/rel-DR01/doc/misc/perlCodeConventions.tex (revision 2595) @@ -0,0 +1,1593 @@ +%%% $Id: perlCodeConventions.tex,v 1.43 2004-12-02 04:17:05 jhoblitt Exp $ +\documentclass[panstarrs]{panstarrs} + +\usepackage{verbatim} + +% basic document variables +\title{Pan-STARRS Image Processing Pipeline} +\subtitle{Perl Code Standards} +\shorttitle{Perl Code Standards} +\author{Joshua Hoblitt} +\audience{Pan-STARRS PMO} +\group{Pan-STARRS Algorithm Group} +\project{Pan-STARRS Image Processing Pipeline} +\organization{Institute for Astronomy} +\version{DR01} +\docnumber{PSDC-430-010} + +\begin{document} +\maketitle +\newcommand{\matchBracket}[1]{} % help emacs match properly + +% -- Revision History -- +\RevisionsStart +% version Date Description +DR00& 2004-11-12 & First Draft\\ +\hline +DR01& 2004-12-01 & Second Draft\\ +\RevisionsEnd + +\textbf{\Large Referenced Documents} +\begin{center} +\begin{tabular}{|p{1in}|p{2.75in}|p{2.75in}|} +\hline +%%% References here. +\textbf{\PS{} ID} & \textbf{Title} & \textbf{Author} \\ +\hline +430-004 &Pan-STARRS IPP C Code Standards &Robert Lupton\\ +\hline +\end{tabular} +\end{center} + +\pagebreak +\tableofcontents + +\pagebreak +\pagenumbering{arabic} + + +%------------------------------------------------------------------------------ + +\section{Introduction} +\subsection{Ancestry} + +This document is derived from the Pan-STARRS IPP C Code Standards document +(PSDC 430-004), which is derived from the Sun Microsystems Java language coding +standards presented in the Java Language Specification\footnote{The Java +Language Specification - http://java.sun.com/docs/books/jls/index.html}. + +\begin{verbatim} + Adapted with permission from + CODE CONVENTIONS FOR THE JAVA^TM PROGRAMMING LANGUAGE. + Copyright 1995-1999 Sun + Microsystems, Inc. All rights reserved. +\end{verbatim} + +See the Java Code Conventions Web site +(\code{http://java.sun.com/docs/codeconv/}) for more details. + +Such an adaption is explicitly permitted by the Sun Microsystems +copyright notice (Copyright.doc.html). + +\subsection{Limitations} + +Although Perl's syntax is similar to that of C or Java, there are many +signification deviations. This has lead to a coding style within the Perl +community that is generally significantly different than that used for C or +Java (See the \code{perlstyle} Pod in the standard Perl documentation for an +example of this). This document does not attempt to define the coding style +common with Perl programmers. Instead, it is an attempt to make the C and Perl +coding styles as consistent as is reasonably feasible within the Pan-STARRS +project. This document contains only a brief discussion of Perl's +Object-Oriented features and none of it's more advanced features. + +\subsection{Applicability} + +This document is intended to be relevant to Perl 5.8.0 or later. + +\subsection{Conformance} + +If any of the conventions established in this document conflict with source +code that has been formated by \code{perltidy} (see \S\ref{perltidy}), the +formatting as output by \code{perltidy} will be considered to be in compliance +with the Perl Code Standards. + +\subsection{To whom should I Complain?} + +While Robert Lupton didn't actually write this document he would enjoy +receiving any complaints or comments it may generate. + +\code{}. + + +%------------------------------------------------------------------------------ + +\section{File Names} + +This section lists commonly used file suffixes and names. + +\subsection{File Suffixes} + +Software uses the following file suffixes: +\begin{center} +\begin{tabular}{ll} +\textbf{File Type}& \textbf{Suffix}\\ +\hline +Perl scripts& \code{.pl}\\ +Perl modules& \code{.pm}\\ +Plain old documentation& \code{.pod}\\ +\end{tabular} +\end{center} + +\subsection{Common File Names} + +Frequently used file names include: +\begin{center} +\begin{tabular}{lp{5in}} +\textbf{File Name}& \textbf{Use}\\ +\hline +\file{Makefile.PL}& +The preferred name for a file that invokes a ``build'' process. Typically this +calls \code{ExtUtils::MakeMaker} or \code{Module::Build} setup the the +necessary files to build and install a module or compile Swig generated C +code.\\ +\end{tabular} +\end{center} + + +%------------------------------------------------------------------------------ + +\section{File Organization} + +General rules: + +\begin{itemize} +\item +A file consists of sections that should be separated by blank lines +and an optional comment identifying each section. + +\item +Files longer than 1000 lines are cumbersome and should be avoided. + +\item +For an example of a properly formatted program, see +Complete Program Example (\S\ref{SourceExample}). + +\item +``Scripts'' have user documentation included at the end of the file. + +\item +``Modules'' have documentation included in a companion \code{.pod}. +\end{itemize} + +\subsection{Source Files} +\subsubsection{Perl Scripts} + +Script files should have the following order: + +\begin{itemize} +\item +A Bourne shell ``she-bang'' for \code{perl}. \code{#!/usr/bin/perl}. + +\item +A Copyright notice followed by a blank commented line. Then one commented line +per CVS keyword to be expanded. + +\item +An optional minimum \code{perl} version requirement in long form (vStrings are +not allowed). Where \code(requirement = revision + version / 1000 + subversion +/ 1\_000\_000). e.g. A minimum requirement of \code{perl} 5.8.5 would be +expressed as \code{use 5.008005}. + +\item +A \code{use strict} and \code{use warnings} declaration. + +\item +An optional \code{$VERSION} declaration. This is useful with +\code{Getopt::Long}'s \code{auto_version} feature. + +\item +Any modules to include. + +\item +Any constant declarations. + +\item +Any script level "globals" declared as lexical variables. e.g. \code{my $foo} + +\item +Any subroutines. + +\item +A \code{__END__} token to instruct the \code{perl} parser to stop looking for +executable code. + +\item +Any Pod documentation about the script. +\end{itemize} + +For an example of a properly organized script, see Script File Example +(\S\ref{foo.pl}). + +\subsubsection{Perl Modules} + +Module files should have the following order: + +\begin{itemize} +\item +A Copyright notice followed by a blank commented line. Then one commented line +per CVS keyword to be expanded. + +\item +A Perl \code{package} declaration. + +\item +An optional minimum \code{perl} version requirement in long form (vStrings are +not allowed). Where \code(requirement = revision + version / 1000 + subversion +/ 1\_000\_000). e.g. A minimum requirement of \code{perl} 5.8.5 would be +expressed as \code{use 5.008005}. + +\item +A \code{use strict} and \code{use warnings} declaration. + +\item +A \code{$VERSION} declaration. + +\item +Any ``base'' classes. + +\item +Any modules to include. + +\item +Any constant declarations. + +\item +Any package variables. e.g. \code{our $foo} + +\item +Any package scoped lexical variables. e.g. \code{my $foo} + +\item +Any subroutines. + +\item +A \code{1} on a line by itself so when the module is parsed it always ends with +a true expression. + +\item +A \code{__END__} token to instruct the perl parser to stop looking for +executable code. + +\end{itemize} + +For an example of a properly organized module, see Module File Example +(\S\ref{Foo.pm}). + +\subsubsection{Plain Old Documentation} +\label{pod} + +Pod files that accompany a module should have the following order: + +\begin{itemize} +\item +A \code{pod} command. + +\item +A \code{NAME} section. + +\item +A \code{SYNOPSIS} section. + +\item +A \code{DESCRIPTION} section. + +\item +A \code{USAGE} section. + +\item +A \code{DEVELOPER NOTES} section. + +\item +A \code{CREDITS} section. + +\item +A \code{SUPPORT} section. + +\item +A \code{AUTHOR} section. + +\item +A \code{COPYRIGHT} section. + +\item +A \code{SEE ALSO} section. + +\item +A \code{cut} command. +\end{itemize} + +For an example of a properly organized Pod, see Pod File Example +(\S\ref{Foo.pod}). + + +%------------------------------------------------------------------------------ + +\section{Indentation} + +Four spaces should be used as the unit of indentation; tabs are forbidden. + +\subsection{Line Length} + +Avoid lines longer than 110 characters. + +When preparing documents, you should ensure that lines of this length +are not wrapped. If you are using the standard PSDC \LaTeX{} class +file \file{panstarrs.cls}, \CODE|\begin{verbatim} ... \end{verbatim}| +will do this for you. + +\subsection{Wrapping Lines} + +When an expression will not fit on a single line, break it according +to these general principles: + +\begin{itemize} +\item Break after a comma or operator. + +\begin{verbatim} + if ($a < $b || + $a > 2*$b) { + $x = ($a + $b + $c) + + sin($z); + } +\end{verbatim} + +\item Prefer higher-level breaks to lower-level breaks. + +\item Indent new lines 4 spaces deeper than the nesting depth of the line on +which the expression began. + +\item If it is convenient to list one statement per line (similar to a hash +declaration) place the closing parenthesis or brace on a new line. + +\end{itemize} + +Here are some examples of breaking subroutine calls: + +\begin{verbatim} + someSub(longExpression1, longExpression2, longExpression3, + longExpression4, longExpression5); + + $var = someSub( + longExpression1, + someSub(longExpression2, longExpression3) + ); +\end{verbatim} + +Following are two examples of breaking an arithmetic expression. The first is +preferred, since the break occurs outside the parenthesized expression, which +is at a higher level. The second is demonstrating a statement being broken at +too low a level. + +\begin{verbatim} + $longName1 = $longName2 * ($longName3 + $longName4 - $longName5) + + 4 * $longName6; # PREFER + + $longName1 = $longName2 * ($longName3 + $longName4 - + $longName5) + 4 * $longName6; # AVOID +\end{verbatim} + +Here are three acceptable ways to format ternary expressions: + +\begin{verbatim} + $alpha = (aLongBooleanExpression) ? $beta : $gamma; + + $alpha = (aLongBooleanExpression) ? $beta + : $gamma; + + $alpha = (aLongBooleanExpression) + ? $beta + : $gamma; +\end{verbatim} + + +%------------------------------------------------------------------------------ + +\section{Comments} + +\subsection{Deactivating Code} + +Comments should not be used to comment out large sections of code. When +deactivating 2 or fewer consecutive lines of code a double hash (\code{##}) +should be used at the very beginning of the line(s). + +Example of deactivating a single line code. + +\begin{verbatim} + if ($foo) { + ## print("foo"); + } +\end{verbatim} + +When deactivating 3 or more lines of code an embedded Pod statement should be +used. The opening statement should be \code{=for off} and the closing +statement should be \code{=cut}. The deactivated section should remain nested +to the same depth as the surrounding code. + +Example of deactivating multiple lines of code. + +\begin{verbatim} + =for off + if ($foo) { + print("foo"); + } + =cut +\end{verbatim} + +\subsection{Implementation Comments} + +General rules: + +\begin{itemize} +\item +Comments should be used to give overviews of code and provide additional +information that is not readily available in the code itself. Comments should +contain only information that is relevant to reading and understanding the +program. For example, information about how the corresponding package is built +or in what directory it resides should not be included as a comment. + +\item +Discussion of nontrivial or non-obvious design decisions is appropriate, but +avoid duplicating information that is present in (and clear from) the code. It +is too easy for redundant comments to get out of date. In general, avoid any +comments that are likely to get out of date as the code evolves. + +\item +Comments should not be enclosed in large boxes drawn with hashes or other +characters. + +\item +Comments should never include special characters such as form-feed and +backspace. +\end{itemize} + +\emph{The frequency of comments sometimes reflects poor quality of code. When +you feel compelled to add a comment, consider rewriting the code to make it +clearer.} + +Programs can have three styles of implementation comments: single-line, +multi-line and trailing. + +\subsubsection{Single-Line Comments} + +Short comments can appear on a single line indented to the level of the code +that follows. The comment should appear above the code that it is describing +and must have a space between the \code{#} and the first text. + +Example of a single-line comment. + +\begin{verbatim} + # some words +\end{verbatim} + +\subsubsection{Multi-Line Comments} + +Merely a repetition of single-line comments. Logically distinct but adjoining +comments should be separated by an empty comment line. + +\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 +\end{verbatim} + +\subsubsection{Trailing Comments} +\label{col41} + +Very short comments can appear on the same line as the code they describe, and +should be indented to column 41\footnote{In emacs, this may be achieved with +\code{ESC;}}. If the code extends beyond this column, the comment should be +separated from the closing semi-colon by a single space. + +Here's an example of a trailing comment in Perl code: + +\begin{verbatim} + if ($a == 2) { + return TRUE; # special case + } else { + return isPrime($a); # works only for odd a + } +\end{verbatim} + +\emph{\code{perltidy}(\S\ref{perltidy}) is incapable of formatting trailing +comments in this style. It will force trailing comments to be 4 spaces to the +right of the last character in any statement on the line. However, it will add +additional spaces to cause trailing comments in adjoining lines to be +vertically aligned. Until such time as \code{perltidy} can following this +convention or a replacement tool is located, trailing comments as formatted by +\code{perltidy} will be considered acceptable.} + +\subsection{API Comments} + +Plain Old Documentation format or Pod will be used to produce documentation of +the subroutines and variables in the exposed API. See Plain Old Documentation +(\S\ref{pod}). + +If you need to give information about a interface, or variable that isn't +appropriate for Podification, use a normal implementation single-line or +multi-line comment immediately \textit{before} the code (as exampled above). + + +%------------------------------------------------------------------------------ + +\section{Declarations} + +\subsection{Lexical Variables} + +One declaration per line with a single place between \code{my} and the identifier: + +\begin{verbatim} + my $level; # indentation level + my $size; # size of table +\end{verbatim} + +is preferred over: + +\begin{verbatim} + my ($level, $size); +\end{verbatim} + +In almost all situations with the exception of when parameters are being passed +into a subroutine or variables are highly related \emph{and} the intent is +plainly obvious. If there is any doubt as to the appropriate style to use +place one declaration per line. + +\begin{verbatim} + my ($verbose, $help); # Correct when the meaning is clear + my ($foo, $bar) = @_; # Correct in a subroutine +\end{verbatim} + +Do not combine different types in the same declaration. Example: + +\begin{verbatim} + my ($foo, @fooArray); # AVOID! +\end{verbatim} + +\subsubsection{Scalars} + +Do not initialize more then one scalar per declaration. + +\begin{verbatim} + my $foo = \$bar; # Correct + my ($foo, $bar) = (1, 2); # AVOID! +\end{verbatim} + +\subsubsection{Arrays} + +When assigning a large number of elements to an array a single column table +format should be used. + +\begin{verbatim} + my @foo = (1, 'two', 3); # Correct + + my @foo = ( # Correct + 1, + 'two', + 3, + 'four', + 5, + 'six', + 7, + 'eight', + 9, + 'ten' + ); + + my @foo = (1, 'two', 3, 'four', 5, 'six', ... # AVOID! +\end{verbatim} + +Consider using the \code{qw} operator when assigning strings to an array. + +\begin{verbatim} + my @foo = qw( 1 two 3 ); + + my @foo = qw( + 1 + two + 3 + four + 5 + six + ); +\end{verbatim} + +\subsubsection{Hashes} + +When assigning a large number of elements to a hash a double column table +format should be used. + +\begin{verbatim} + my %foo = (one => 1, two => 2); # Correct + + my %foo = ( # Correct + one => 1, + two => 2, + three => 3, + four => 4, + five => 5, + six => 6, + seven => 7, + eight => 8, + nine => 9, + ten => 10 + ); + + my %foo = (one => 1, two => 2, three => 3, ... # AVOID! +\end{verbatim} + +\subsection{Local Variables} + +Avoid \code{local} declarations that hide user declared variables from higher +level scopes. For example, do not declare the same variable name in an inner +block: + +\begin{verbatim} + my $count; + ... + sub mySubroutine + { + local $count; # AVOID! + ... + } +\end{verbatim} + +\emph{This restriction does not apply to Perl's built in variables.} + +\subsection{Package Variables} + +See When to Make Symbols Global (\S\ref{globals}). + +\subsection{Initialization} + +General rules: + +\begin{itemize} +\item +Try to initialize local variables where they're declared. + +\item +Do not initialize variables with an empty string or list - this is pointless. + +\item +A reason not to initialize a variable where it's declared is if the initial +value depends on some computation occurring first. + +\item +In some cases it may be necessary to initialize a variable to suppress a +compiler warning; in this case a comment should explain the circumstances. +\end{itemize} + +\subsection{Placement} + +Variables should ordinarily be declared at the top of the block in +which they appear, unless there is some reason to declare them later. +This allows them to be initialized as they are created, and naturally +associates their declaration with their use. + +\subsection{Subroutine Declarations} + +When coding subroutines the following formatting rules should be +followed: + +\begin{itemize} +\item +Subroutine declarations may be preceded by a short comment describing what the +subroutine does. These comments should include a brief description as well as +other warnings, bugs, etc. as needed. + +\item +The subroutine body's open brace \CODE.{. should be in column 1 of the next +line. + +\item +The first line after the opening brace should declare a list of lexical +variables for input parameters and assign \code{shift} or \code{@_} to it. + +\item +Closing brace \CODE.}. starts a line by itself. + +\item +The last line before the closing brace must explicitly declare a return value. + +\item +Do not directly use the \code{@_} array. + +\item +Do not nest named subroutines. +\end{itemize} + +\begin{verbatim} + sub subName # Correct + { + my $param = shift; + ... + return $val; + } + + sub subName # Correct + { + my ($param1, $param2, ...) = @_; + ... + return $val; + } + + sub subName # AVOID! + { + if ($_[0] eq "foo") { + ... + } +\end{verbatim} + + +%------------------------------------------------------------------------------ + +\section{Statements} +\subsection{Simple Statements} + +Each line should usually contain only one statement. Example: + +\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} + +where the two actions are intimately related. + +\subsection{Compound Statements} + +Compound statements are statements that contain lists of statements enclosed in +braces. See the following sections for examples. + +\begin{itemize} +\item The enclosed statements should be indented one more level than the compound statement. + +\item The opening brace should be at the end of the line that begins +the compound statement; the closing brace should begin a line and be +indented to the beginning of the compound statement. +\end{itemize} + +\subsection{return Statements} + +A \code{return} statement with a value should not use parentheses unless they +make the return value more obvious in some way. All subroutines must have an +explicit, non-null, return statement. Example: + +\begin{verbatim} + return undef; # Correct + return; # AVOID! + return $myDisk->size; # Correct + return ($size ? $size : $defaultSize); # Correct +\end{verbatim} + +\emph{In the absence of an explicit return statement Perl will return the +results of the last statement executed. A null \code{return} statement also +causes the result of the last statement executed to be returned. Relying on +this behavior is likely to confuse maintenance programmers and therefore should +be avoided.} + +\subsection{if, if-else, if-elsif-else Statements} + +\code{if} statements must always use parentheses \code{()} around conditionals. + +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; + } +\end{verbatim} + +\subsection{C style for Statements} + +A \code{for} statement should have the following form: + +\begin{verbatim} + for (initialization; condition; update) { + statements; + } +\end{verbatim} + +For example: + +\begin{verbatim} + for (my $i = 0; $i < 100; $i++) { + print "$i\n"; + } +\end{verbatim} + +An empty \code{for} statement (one in which all the work is done in the +initialization, condition, and update clauses) should have the following forms: + +\begin{verbatim} + for (initialization; condition; update) {} +\end{verbatim} + +When using the comma operator in the initialization or update clause +of a \code{for} statement, avoid the complexity of using more +than three variables. If needed, use separate statements before the +\code{for} loop (for the initialization clause) or at the end of +the loop (for the update clause). + +\subsection{Perl style for, foreach Statements} + +A Perlish \code{for} or \code{foreach} statement should have the following +form: + +\begin{verbatim} + foreach my $item (@workingList) { + # do stuff with $item + } +\end{verbatim} + +The current working item should be interacted with through a declared lexical +variable and not via \code{$_}. + +\begin{verbatim} + foreach (@workingList) { # AVOID! + # do stuff with $_ + } +\end{verbatim} + +\subsection{while Statements} + +A \code{while} statement should have the following form: + +\begin{verbatim} + while (condition) { + statements; + } +\end{verbatim} + +An empty \code{while} statement should have the following form: + +\begin{verbatim} + while (condition) {} +\end{verbatim} + +\subsection{do-while Statements} + +A \code{do-while} statement should have the following form: + +\begin{verbatim} + do { + statements; + } while (condition); +\end{verbatim} + +\subsection{Label Statements} + +Code labels should be indented to align with the previous level of +indentation. + +\begin{verbatim} + MYLABEL: while (condition) { + if (condition) { + next MYLABEL; + } + } +\end{verbatim} + +\subsection{Blocks} + +The contense of a block should be idented one level. + +\begin{verbatim} + $foo = foobar($baz); + { + my $bat = fooBaz(); + ... + } +\end{verbatim} + + +%------------------------------------------------------------------------------ + +\section{White Space} +\subsection{Blank Lines} + +Blank lines improve readability by setting off sections of code that +are logically related. + +Two blank lines should always be used in the following circumstances: +\begin{itemize} +\item +Between sections of a source file +\end{itemize} + +One blank line should always be used in the following circumstances: + +\begin{itemize} +\item +Between the local variables in a subroutine and its first statement + +\item +Between logical sections inside a subroutine to improve readability +\end{itemize} + +\subsection{Blank Spaces} + +Blank spaces should be used in the following circumstances: +\begin{itemize} +\item +A keyword followed by a parenthesis should be separated by a space. Example: + +\begin{verbatim} + while (true) { + ... + } +\end{verbatim} + +\emph{A blank space should not be used between a subroutine name and its +opening parenthesis. This helps to distinguish keywords from subroutine calls.} + +\item +A blank space should appear after commas in parameter lists. + +\begin{verbatim} + subName(1, 2, 3); +\end{verbatim} + +\item +Binary operators should be separated from their operands by spaces. Blank +spaces should never separate unary operators such as a unary minus, increment +(\code{++}), and decrement (\code{--}) from their operands. Examples: + +\begin{verbatim} + $a += $c + $d; + $a = ($a + $b) / ($c * $d); + + while ($d++ = $s++) { + $n++; + } + printf("size is %d\n", $foo); +\end{verbatim} + +\item +The expressions in a \code{for} statement should be separated by blank spaces. +Example: + +\begin{verbatim} + for (expr1; expr2; expr3) {} +\end{verbatim} + +\item +Built-in quoting functions should have spaces between their parameters and the +opening/closing delimiters. + +\begin{verbatim} + my @things = qw( foo bar baz ); +\end{verbatim} +\end{itemize} + +Blank spaces should \textit{not} be used in the following circumstances: + +\begin{itemize} +\item +A variable dereference or method call should not have any blank spaces around +the \code{->} operator. + +\begin{verbatim} + $myHashRef->{'foo'}; + $myObject->foo; +\end{verbatim} + +\end{itemize} + + +%------------------------------------------------------------------------------ + +\section{Naming Conventions} + +Naming conventions make programs more understandable by making them easier to +read. They can also give information about the subroutine of the identifier -- +for example, whether it's a constant or a subroutine -- which can be helpful in +understanding the code. Remember these are guidelines for improving +readability; clarity should trump rigid adherence to the guideline. + +{ \small +\begin{tabular}{lp{3in}p{3in}} +\textbf{Identifier Type} & +\textbf{Rules for Naming} & +\textbf{Examples} \\ +\hline\\ + +Script Files & + +The filenames of all scripts should be verbal phrases, in mixed case. The +capitalized \code{.PL} suffix is reserved for ``build'' scripts. + +& + +\code{foo.pl}\hfil\break +\code{fooBar.pl}\hfil\break +\code{Makefile.PL}\hfil\break + +\\ + +Module Files & + +The filenames of all modules should be verbal phrases, in mixed case, with the +first letter capitalized. + +& + +\code{Foo.pm}\hfil\break +\code{FooBar.pm}\hfil\break + +\\ + +Pod Files & + +The filenames of all stand-alone Pod should follow the same rules as module +files. + +& + +\code{Foo.pod}\hfil\break +\code{FooBar.pod}\hfil\break + +\\ + +Subroutines & + +The names of all public subroutines (and methods) should be verbal phrases, in +mixed case. + +Private subroutines (and methods) should follow the same rules as public +subroutines but be prefixed with an underscore. + +& + +\code{run();}\hfil\break +\code{runFast();}\hfil\break +\code{getBackground();}\hfil\break +\code{_keepHandsOff();}\hfil\break + +\\ + +Variables & + +Variable names should be in mixed case and be short yet meaningful. The choice +of a variable name should be mnemonic- that is, designed to indicate to the +casual observer the intent of its use. One-character variable names should be +avoided except for temporary \textit{throwaway} variables. Common names for +temporary variables are \code{$i}, \code{$j}, \code{$k}, \code{$m}, and \code{$n} +for integers; \code{$c}, \code{$d}, and \code{$e} for characters. + +& + +\code{$i;}\hfil\break +\code{$i;}\hfil\break +\code{$c;}\hfil\break +\code{$myWidth;}\hfil\break +\code{$pseudo;}\hfil\break +\code{$myFiddleFactor;}\hfil\break + +\\ + +Constants & + +Constant names should be in all capital letters and highly descriptive. + +& +\code{use constant PI => 3.14159265;}\hfil\break +\code{use constant LENGTHS => qw( 2, 4, 8 );}\hfil\break +\code{use constant CLASSES => {a => 1, b => 2};}\hfil\break + +\\ + +Namespaces & + +Must start with a capitalized letter but otherwise follow the same naming +conventions as variables. + +& + +\code{package PS::IPP::Metadata;}\hfil\break +\code{package PS::IPP::Modules::Debias;}\hfil\break +\code{package PS::MOPS::DB::Detections;}\hfil\break +\code{package PS::MOPS::Util::MPC;}\hfil\break + +\\ + +Labels & + +Label names should be in all capital letters and short. Generally they should +attempt to describe the `thing' being operated on by the loop they are labeling. + +& + +\code{LINE:}\hfil\break +\code{CONNECTION:}\hfil\break +\code{IMAGE:}\hfil\break + +\\ + +\end{tabular} +} + + +%------------------------------------------------------------------------------ + +\section{Programming Practices} + +\subsection{When to Make Symbols Global} +\label{globals} + +Only declare variables as package variables (\code{our}) if they are intended +to be visible outside of the current namespace. All other variables within a +namespace should be declared as lexical. + +\begin{verbatim} + our $VERSION = '1.00'; # Correct + our $localCounter; # AVOID! - should be lexical + + use base qw( Exporter ); + our @EXPORT_OK = qw( $foo $bar ); # Correct +\end{verbatim} + +\subsection{Constants} + +Numerical constants (literals) should not be coded directly, except for +small integers such as -1, 0, and 1 which are permitted to e.g. appear +in a \code{for} loop as counter values. + +The \code{constant} pragma should be used to declare constants. +\emph{``constants'' created this way can not be interpolated inside of double +quoted strings.} + +See the \code{constant} module's Pod for further details. + +\subsection{Variable Assignments} + +Avoid assigning several variables to the same value in a single +statement, unless the variables are intimately related. Acceptable examples: + +\begin{verbatim} + $row0 = $col0 = 0; + $sum = $sumx = $sumy = 0; +\end{verbatim} + +Do not use the assignment operator in a place where it can be easily confused +with the equality operator. Example: + +\begin{verbatim} + if ($c++ = $d++) { # AVOID! + ... + } +\end{verbatim} + +should be written as: + +\begin{verbatim} + 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! +\end{verbatim} + +should be written as + +\begin{verbatim} + $a = $b + $c; + $d = $a + $r; +\end{verbatim} + +\subsection{Miscellaneous Practices} +\subsubsection{Parentheses} + +It is generally a good idea to use parentheses liberally in +expressions involving mixed operators to avoid operator precedence +problems. Even if the operator precedence seems clear to you, it might +not be to others-you shouldn't assume that other programmers know +precedence as well as you do. In cases where the precedence rules +are clear, the parentheses may be omitted. + +\begin{verbatim} + if ($a & $b || $c & $d) {} # AVOID! + if (($a & $b) || ($c & $d)) {} # Correct +\end{verbatim} + +In particular, expressions involving the combinations of \code{||} and +\code{&&} should be fully parenthesized, as should all expressions containing +bitwise operators: + +\begin{verbatim} + if (($a == $b && $c == $d) || $e == $f) {} + $l << ($j + $k) + ($l << $j) + $k + ($i & $b) | $c +\end{verbatim} + +\subsubsection{Returning Values} + +Try to make the structure of your program match the intent. Example: + +\begin{verbatim} + if (booleanExpression) { + return true; + } else { + return false; + } +\end{verbatim} + +should instead be written as + +\begin{verbatim} + return booleanExpression; +\end{verbatim} + +If you're concerned that the reader may not know that \code{booleanExpression} +is boolean, use: + +\begin{verbatim} + return (booleanExpression ? true : false); +\end{verbatim} + +Similarly, + +\begin{verbatim} + if (condition) { + return $x; + } + return $y; +\end{verbatim} + +should be written as + +\begin{verbatim} + return (condition ? x : y); +\end{verbatim} + +\subsubsection{Expressions before `?' in the Conditional Operator } + +If an expression containing a binary operator appears before the \code{?} in +the ternary \code{?:} operator, it should be parenthesized. Example: + +\begin{verbatim} + ($x >= 0) ? $x : -$x; +\end{verbatim} + +\subsubsection{\$\_} + +Use of the ``default'' variable (\code{$_}) should be avoided. + +\begin{verbatim} + my $foo =~ /(foo.*)/; # Correct + foreach my $foo (@bar) {} # Correct + /(foo.*)/; # AVOID! + $_ = ~/(foo.*)/; # AVOID! +\end{verbatim} + +\subsubsection{FileHandles} + +Do not use ``bare-words'' as filehandles except for \code{STDIN}, \code{STDOUT}, +and \code{STDERR}. + +\begin{verbatim} + open(STDOUT, '>', $foo) or die "can not open STDOUT: $!"; # Correct + open(my $fh, '>', $foo) or die "can not open file $foo: $!"; # Correct + open(FILE, '>', $foo) or die "can not open file $foo: $!"; # AVOID! +\end{verbatim} + +\subsubsection{System Calls} + +Always check the return code of system calls. + +\begin{verbatim} + open(my $fh, '>', $foo) or die "can not open file $foo: $!"; # Correct + close($fh) or die "can not close file $foo: $!"; # Correct + chdir($foo); # AVOID! +\end{verbatim} + +\subsubsection{Chop vs. Chomp} + +Do not use \code{chop} to remove newline characters as it will remove any +character (newline or not). + +\begin{verbatim} + my $foo = "baz\n"; # string with newline + chomp($foo); # removes "\n" - Correct + chomp($foo); # chomping the same string twice is safe + chop($foo); # removes "z" - AVOID! +\end{verbatim} + +\subsubsection{Array Subscripts} + +Use ``cuddled'' brackets \code{[]} when accessing an array element. + +\begin{verbatim} + $foo[-1]; # Correct + (someSub($foo))[1]; # Correct + $foo[ 6 ]; # AVOID! +\end{verbatim} + +\subsubsection{Hash Subscripts} + +Use ``cuddled'' brackets \CODE.{}. when accessing a hash element. It is +acceptable to use ``bare-words'' as a hash key (\emph{this rule may be subject +to change}). + +\begin{verbatim} + $foo{bar}; # Correct + $foo{$baz}; # Correct + $foo{'fiddle'}; # Correct + $foo{ lish }; # AVOID! + $foo{ 'zab' }; # AVOID! +\end{verbatim} + +\subsubsection{Loading Modules} + +Modules may be loaded with an optional version requirement. This is +particularly useful for modules that exist in the Perl core but have newer +versions available on CPAN. + +\begin{verbatim} + use Foo; # Correct + use Foo 0.02; # Correct +\end{verbatim} + +Do not use \code{require} to prevent a module from exporting symbols into the +caller's namespace. Instead, provide \code{use} with an empty parameter list. + +\begin{verbatim} + use Foo qw(); # Correct + use Foo (); # Correct + require Foo; # AVOID! +\end{verbatim} + +This also works with a minimum module version requirement. + +\begin{verbatim} + use Foo 0.02 qw(); # Correct +\end{verbatim} + +\subsubsection{Inheritance} + +Do not use the \code{@ISA} package variable for subclassing. Instead, use the +\code{base} pragma. + +\begin{verbatim} + use base qw( Foo ); # Correct + our @ISA = qw( Foo ); # AVOID! +\end{verbatim} + +\subsubsection{Calling Subroutines} + +Do not use the \code{&} sigil to to disambiguate a subroutine from a +``bare-word''. Instead, use empty parentheses adjoined to the subroutine call. + +\emph{Only use the \code{subs} pragma as a last resort.} + +\begin{verbatim} + fooBar($foo); # Correct + fooBar(); # Correct + &fooBar; # AVOID! + &fooBar(); # AVOID! + use subs qw( fooBar ); # last resort - Correct +\end{verbatim} + +\subsubsection{Calling Methods} + +Leave the parentheses off method calls that aren't being passed parameters. + +\begin{verbatim} + $myObj->fooBar; # Correct + $myObj->fooBar($foo); # Correct + $myObj->fooBar(); # AVOID! +\end{verbatim} + +\subsubsection{Quoting Strings} + +\begin{itemize} +\item +Unless variable interpolation needs to occur inside of a string or is likely to +be needed in the future, use single quotes \code{''} instead of double quotes +\code{""}. + +\item +When possible use \code{END} as the termination token for ``\code{< { + type => OBJECT, + isa => 'HTTP::Request', + }, + length => { + type => SCALAR, + callbacks => { + 'length is > 0' => sub { $_[0] > 0 }, + 'length is + integer' => sub { $_[0] =~ /^\d+$/ }, + }, + }, + segments => { + type => SCALAR, + default => 4, + callbacks => { + 'segments is > 1' => sub { $_[0] > 1 }, + 'segments is + integer' => sub { $_[0] =~ /^\d+$/ }, + 'segments is <= length' => sub { $_[0] <= $_[1]->{ 'length' } }, + }, + }, + }, + ); + +\end{verbatim} + +Please see the \code{Params::Validate} Pod\footnote{Params::Validate Pod - +http://search.cpan.org/~drolsky/Params-Validate/lib/Params/Validate.pm} for +further details. + + +%------------------------------------------------------------------------------ + +\bibliographystyle{plain} +\bibliography{panstarrs} + +\end{document}