Changeset 2403 for trunk/doc/misc/perlCodeConventions.tex
- Timestamp:
- Nov 22, 2004, 6:24:52 PM (22 years ago)
- File:
-
- 1 edited
-
trunk/doc/misc/perlCodeConventions.tex (modified) (16 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/misc/perlCodeConventions.tex
r2401 r2403 1 %%% $Id: perlCodeConventions.tex,v 1.2 6 2004-11-23 02:53:47jhoblitt Exp $1 %%% $Id: perlCodeConventions.tex,v 1.27 2004-11-23 04:24:52 jhoblitt Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 77 77 common with Perl programmers. Instead, it is an attempt to make the C and Perl 78 78 coding styles as consistent as is reasonably feasible within the Pan-STARRS 79 project. This document alsoonly contains brief discussion of Perl's79 project. This document only contains brief discussion of Perl's 80 80 Object-Oriented features and none of it's more advanced features. 81 81 82 82 \subsection{Applicability} 83 83 84 This document is intended to be relevant withPerl 5.8.0 or later.84 This document is intended to be relevant to Perl 5.8.0 or later. 85 85 86 86 \subsection{To whom should I Complain?} … … 148 148 \begin{itemize} 149 149 \item 150 A Bourne shell "she-bang"for perl. \code{#!/usr/bin/perl}.150 A Bourne shell ``she-bang'' for perl. \code{#!/usr/bin/perl}. 151 151 152 152 \item … … 155 155 156 156 \item 157 A minimum perl version requirement in long form (vStrings are not allowed).158 Where \code(requirement = revision + version / 1000 + subversion /157 An optional minimum perl version requirement in long form (vStrings are not 158 allowed). Where \code(requirement = revision + version / 1000 + subversion / 159 159 1\_000\_000). E.g. A minimum requirement of Perl 5.8.5 would be expressed as 160 160 \code{use 5.008005} … … 164 164 165 165 \item 166 Any base classes.166 Any modules to include. 167 167 168 168 \item … … 202 202 203 203 \item 204 A minimum perl version requirement in long form (vStrings are not allowed).204 An optional minimum perl version requirement in long form (vStrings are not allowed). 205 205 Where \code(requirement = revision + version / 1000 + subversion / 1\_000\_000). 206 206 E.g. A minimum requirement of Perl 5.8.5 would be expressed as \code{use … … 210 210 A \code{use strict} and \code{use warnings} declaration. 211 211 212 \item 213 A module \code{VERSION} declaration. 214 215 \item 216 Any ``base'' classes. 217 212 218 \item 213 219 Any modules to include. … … 237 243 238 244 \subsubsection{Plain Old Documentation} 245 \label{pod} 239 246 240 247 This is the format for documentation in a \code{.pl} file after the 241 \code{__END__} token and the \code{.pod} file that should accompany a 242 a module(\code{.pm}).248 \code{__END__} token and the \code{.pod} file that should accompany a module 249 (\code{.pm}). 243 250 244 251 e.g. for file Foo.pod: … … 432 439 \end{verbatim} 433 440 434 \subsection{ DocumentationComments}441 \subsection{API Comments} 435 442 \label{DocComments} 436 443 437 444 Plain Old Documentation format or Pod will be used to produce documentation of 438 the subroutines and variables in the exposed API. Pod sections will appear 439 above the section of code that they describe. 440 441 An example of a Pod section defining the API of a subroutine. 442 443 \begin{verbatim} 444 =item * reallyCoolSubroutine 445 446 Accepts a real number and a string. Does some really cool stuff with it and 447 returns a really cool thing. 448 449 =cut 450 451 sub reallyCoolSubroutine 452 { 453 my ($aNumber, $aString) = @_; 454 455 # Do really cool stuff 456 457 return $aThing; 458 } 459 \end{verbatim} 445 the subroutines and variables in the exposed API. See Plain Old Documentation 446 (\S\ref{pod}). 460 447 461 448 If you need to give information about a interface, or variable that isn't 462 449 appropriate for Podification, use a normal implementation single-line or 463 multi-line comment 450 multi-line comment immediately \textit{before} the code (as exampled above). 464 451 465 452 … … 511 498 \subsection{Initialization} 512 499 513 Try to initialize local variables where they're declared. Do not initialize 514 variables with an empty string or list - this is pointless. 515 516 reason not to initialize a variable where it's declared is if the 517 initial value depends on some computation occurring first. 500 Try to initialize local variables where they're declared. 501 502 Do not initialize variables with an empty string or list - this is pointless. 503 504 A reason not to initialize a variable where it's declared is if the initial 505 value depends on some computation occurring first. 518 506 519 507 In some cases it may be necessary to initialize a variable to suppress … … 534 522 \begin{itemize} 535 523 \item 536 Subroutine declarations should be preceded by a short comment describing what537 the subroutine does. These documentation comments should include a brief 538 description as well asother warnings, bugs, etc. as needed.524 Subroutine declarations may be preceded by a short comment describing what the 525 subroutine does. These comments should include a brief description as well as 526 other warnings, bugs, etc. as needed. 539 527 540 528 \item … … 547 535 548 536 \item 549 Closing brace \CODE.}. starts a line by itself , except when it is a null550 statement the \CODE.}. should appear immediately after the \CODE.{..537 Closing brace \CODE.}. starts a line by itself. Null statement should have the 538 closing brace immediately after the opening brace. e.g. \CODE.{}. 551 539 552 540 \item … … 684 672 \subsection{Perl style for, foreach Statements} 685 673 686 A Perlish \code{for} or \code{foreach} statement (also known as an iterator)687 should have the followingform:674 A Perlish \code{for} or \code{foreach} statement should have the following 675 form: 688 676 689 677 \begin{verbatim} … … 1042 1030 1043 1031 If an expression containing a binary operator appears before the \code{?} in 1044 the ternary \code{?: }operator, it should be parenthesized. Example:1032 the ternary \code{?:} operator, it should be parenthesized. Example: 1045 1033 1046 1034 \begin{verbatim} … … 1062 1050 1063 1051 Don't use ``bare-words'' as filehandles except for \code{STDIN}, \code{STDOUT}, 1064 or\code{STDERR}.1052 and \code{STDERR}. 1065 1053 1066 1054 \begin{verbatim} … … 1080 1068 \end{verbatim} 1081 1069 1070 \subsubsection{Chop vs. Chomp} 1071 1072 Don't use \code{chop} to remove newline characters as it will remove any 1073 character (newline or not). 1074 1075 \begin{verbatim} 1076 my $foo = "baz\n"; # string with newline 1077 1078 chomp($foo); # removes "\n" - Correct 1079 chomp($foo); # chomping the same string twice is safe 1080 1081 chop($foo); # removes "z" - AVOID! 1082 \end{verbatim} 1083 1082 1084 %------------------------------------------------------------------------------ 1083 1085 \appendix %Begin Appendices
Note:
See TracChangeset
for help on using the changeset viewer.
