Changeset 2594 for trunk/doc/misc/perlCodeConventions.tex
- Timestamp:
- Dec 1, 2004, 6:17:05 PM (22 years ago)
- File:
-
- 1 edited
-
trunk/doc/misc/perlCodeConventions.tex (modified) (19 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/misc/perlCodeConventions.tex
r2591 r2594 1 %%% $Id: perlCodeConventions.tex,v 1.4 2 2004-12-01 22:34:22jhoblitt Exp $1 %%% $Id: perlCodeConventions.tex,v 1.43 2004-12-02 04:17:05 jhoblitt Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 54 54 This document is derived from the Pan-STARRS IPP C Code Standards document 55 55 (PSDC 430-004), which is derived from the Sun Microsystems Java language coding 56 standards presented in the Java Language Specification 57 58 (\code{http://java.sun.com/docs/books/jls/index.html}). 56 standards presented in the Java Language Specification\footnote{The Java 57 Language Specification - http://java.sun.com/docs/books/jls/index.html}. 59 58 60 59 \begin{verbatim} … … 80 79 common with Perl programmers. Instead, it is an attempt to make the C and Perl 81 80 coding styles as consistent as is reasonably feasible within the Pan-STARRS 82 project. This document only containsbrief discussion of Perl's81 project. This document contains only a brief discussion of Perl's 83 82 Object-Oriented features and none of it's more advanced features. 84 83 … … 129 128 \hline 130 129 \file{Makefile.PL}& 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 The preferred name for a file that invokes a ``build'' process. Typically this 131 calls \code{ExtUtils::MakeMaker} or \code{Module::Build} setup the the 132 necessary files to build and install a module or compile Swig generated C 133 code.\\ 134 134 \end{tabular} 135 135 \end{center} … … 178 178 not allowed). Where \code(requirement = revision + version / 1000 + subversion 179 179 / 1\_000\_000). e.g. A minimum requirement of \code{perl} 5.8.5 would be 180 expressed as \code{use 5.008005} 180 expressed as \code{use 5.008005}. 181 181 182 182 \item … … 226 226 not allowed). Where \code(requirement = revision + version / 1000 + subversion 227 227 / 1\_000\_000). e.g. A minimum requirement of \code{perl} 5.8.5 would be 228 expressed as \code{use 5.008005} 228 expressed as \code{use 5.008005}. 229 229 230 230 \item … … 268 268 \label{pod} 269 269 270 This is the format for documentation in a \code{.pod} file that should 271 accompany a module. 270 Pod files that accompany a module should have the following order: 271 272 \begin{itemize} 273 \item 274 A \code{pod} command. 275 276 \item 277 A \code{NAME} section. 278 279 \item 280 A \code{SYNOPSIS} section. 281 282 \item 283 A \code{DESCRIPTION} section. 284 285 \item 286 A \code{USAGE} section. 287 288 \item 289 A \code{DEVELOPER NOTES} section. 290 291 \item 292 A \code{CREDITS} section. 293 294 \item 295 A \code{SUPPORT} section. 296 297 \item 298 A \code{AUTHOR} section. 299 300 \item 301 A \code{COPYRIGHT} section. 302 303 \item 304 A \code{SEE ALSO} section. 305 306 \item 307 A \code{cut} command. 308 \end{itemize} 272 309 273 310 For an example of a properly organized Pod, see Pod File Example … … 334 371 335 372 \begin{verbatim} 336 $longName1 = $longName2 *($longName3 + $longName4 - $longName5) +337 4 *$longname6; # PREFER373 $longName1 = $longName2 * ($longName3 + $longName4 - $longName5) + 374 4 * $longName6; # PREFER 338 375 339 $longName1 = $longName2 *($longName3 + $longName4 -340 $longName5) + 4 *$longname6; # AVOID376 $longName1 = $longName2 * ($longName3 + $longName4 - 377 $longName5) + 4 * $longName6; # AVOID 341 378 \end{verbatim} 342 379 … … 373 410 \end{verbatim} 374 411 375 When deactivating 3 or more lines of code an \code{if} statement should be used376 with a false boolean value. The opening and closing of the \code{if} statement 377 s hould be nested to the same depth as the surrounding code and the deactivated378 section should be indented.412 When deactivating 3 or more lines of code an embedded Pod statement should be 413 used. The opening statement should be \code{=for off} and the closing 414 statement should be \code{=cut}. The deactivated section should remain nested 415 to the same depth as the surrounding code. 379 416 380 417 Example of deactivating multiple lines of code. 381 418 382 419 \begin{verbatim} 383 if (0) {384 385 386 387 }420 =for off 421 if ($foo) { 422 print("foo"); 423 } 424 =cut 388 425 \end{verbatim} 389 426 … … 425 462 426 463 Short comments can appear on a single line indented to the level of the code 427 that follows. The comment should appear above the code that it is describ e and428 must have a space between the \code{#} and the first text.464 that follows. The comment should appear above the code that it is describing 465 and must have a space between the \code{#} and the first text. 429 466 430 467 Example of a single-line comment. … … 512 549 \end{verbatim} 513 550 514 Do not put different types on the same line. Example:551 Do not combine different types in the same declaration. Example: 515 552 516 553 \begin{verbatim} … … 659 696 660 697 \item 661 Closing brace \CODE.}. starts a line by itself. Null statement should have the 662 closing brace immediately after the opening brace. e.g. \CODE.{}. 698 Closing brace \CODE.}. starts a line by itself. 663 699 664 700 \item … … 750 786 \subsection{if, if-else, if-elsif-else Statements} 751 787 752 \code{if} statements must always use braces \{\} around statements and parentheses 753 () around conditionals. 788 \code{if} statements must always use parentheses \code{()} around conditionals. 754 789 755 790 The \code{if-else} class of statements should have the following form: … … 865 900 \end{verbatim} 866 901 902 \subsection{Blocks} 903 904 The contense of a block should be idented one level. 905 906 \begin{verbatim} 907 $foo = foobar($baz); 908 { 909 my $bat = fooBaz(); 910 ... 911 } 912 \end{verbatim} 913 867 914 868 915 %------------------------------------------------------------------------------ … … 949 996 \begin{itemize} 950 997 \item 951 A dereferencing or method call should not have any blank spaces around the952 \code{->} operator.998 A variable dereference or method call should not have any blank spaces around 999 the \code{->} operator. 953 1000 954 1001 \begin{verbatim} … … 958 1005 959 1006 \end{itemize} 1007 1008 960 1009 %------------------------------------------------------------------------------ 961 1010 … … 1051 1100 Constants & 1052 1101 1053 Constant names should be in all capital letters and highly descriptive. The 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.} 1102 Constant names should be in all capital letters and highly descriptive. 1057 1103 1058 1104 & … … 1119 1165 in a \code{for} loop as counter values. 1120 1166 1167 The \code{constant} pragma should be used to declare constants. 1168 \emph{``constants'' created this way can not be interpolated inside of double 1169 quoted strings.} 1170 1171 See the \code{constant} module's Pod for further details. 1172 1121 1173 \subsection{Variable Assignments} 1122 1174 … … 1138 1190 \end{verbatim} 1139 1191 1140 should be written as 1192 should be written as: 1141 1193 1142 1194 \begin{verbatim}
Note:
See TracChangeset
for help on using the changeset viewer.
