Changeset 2334
- Timestamp:
- Nov 10, 2004, 4:27:56 PM (22 years ago)
- File:
-
- 1 edited
-
trunk/doc/misc/perlCodeConventions.tex (modified) (20 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/misc/perlCodeConventions.tex
r2333 r2334 1 %%% $Id: perlCodeConventions.tex,v 1. 3 2004-11-11 02:00:42jhoblitt Exp $1 %%% $Id: perlCodeConventions.tex,v 1.4 2004-11-11 02:27:56 jhoblitt Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 127 127 A Bourne shell "she-bang" for perl. \code{#!/usr/bin/perl}. 128 128 \item 129 A Cop right notice followed by a blank commented line. Then one commented line129 A Copyright notice followed by a blank commented line. Then one commented line 130 130 per CVS keyword to be expanded. 131 131 \item 132 A minimum perl version requirem t in long form (vStrings are not allowed).133 Where \code(requ riemnt = revision + version / 1000 + subversion / 1\_000\_000).132 A minimum perl version requirement in long form (vStrings are not allowed). 133 Where \code(requirement = revision + version / 1000 + subversion / 1\_000\_000). 134 134 E.g. A minimum requirement of Perl 5.8.5 would be expressed as \code{use 135 135 5.008005} … … 155 155 # Copyright (C) 2004 Joshua Hoblitt 156 156 # 157 # $Id: perlCodeConventions.tex,v 1. 3 2004-11-11 02:00:42jhoblitt Exp $157 # $Id: perlCodeConventions.tex,v 1.4 2004-11-11 02:27:56 jhoblitt Exp $ 158 158 159 159 use 5.008005; # optional … … 181 181 \begin{itemize} 182 182 \item 183 A Cop right notice followed by a blank commented line. Then one commented line183 A Copyright notice followed by a blank commented line. Then one commented line 184 184 per CVS keyword to be expanded. 185 185 \item 186 186 A Perl Package declaration. \code{package Foo} 187 187 \item 188 A minimum perl version requirem t in long form (vStrings are not allowed).189 Where \code(requ riemnt = revision + version / 1000 + subversion / 1\_000\_000).188 A minimum perl version requirement in long form (vStrings are not allowed). 189 Where \code(requirement = revision + version / 1000 + subversion / 1\_000\_000). 190 190 E.g. A minimum requirement of Perl 5.8.5 would be expressed as \code{use 191 191 5.008005} … … 212 212 # Copyright (C) 2004 Joshua Hoblitt 213 213 # 214 # $Id: perlCodeConventions.tex,v 1. 3 2004-11-11 02:00:42jhoblitt Exp $214 # $Id: perlCodeConventions.tex,v 1.4 2004-11-11 02:27:56 jhoblitt Exp $ 215 215 216 216 package Foo; … … 355 355 should not be included as a comment. 356 356 357 Discussion of nontrivial or non obvious design decisions is357 Discussion of nontrivial or non-obvious design decisions is 358 358 appropriate, but avoid duplicating information that is present in (and 359 359 clear from) the code. It is too easy for redundant comments to get out … … 389 389 \subsubsection{Multi-Line Comments} 390 390 391 Merely a rep itition of single-line comments.391 Merely a repetition of single-line comments. 392 392 393 393 \subsubsection{Trailing Comments} … … 464 464 465 465 In almost all situations with the exception of when parameters are being passed 466 into a subr utine.466 into a subroutine. 467 467 468 468 Do not put different types on the same line. Example: … … 487 487 \end{verbatim} 488 488 489 Note: This rest iction does not apply to Perl's built in variables.489 Note: This restriction does not apply to Perl's built in variables. 490 490 491 491 \subsection{Initialization} … … 502 502 Variables should ordinarily be declared at the top of the block in 503 503 which they appear, unless there is some reason to declare them later. 504 This allows them to be initiali sed as they are created, and naturally504 This allows them to be initialized as they are created, and naturally 505 505 associates their declaration with their use. 506 507 508 Indexes of loops should usually be declared on the line above loop statement.509 510 \begin{verbatim}511 my $i = 0;512 for (i < $maxLoops) {513 # do stuff514 515 $i++;516 }517 \end{verbatim}518 506 519 507 \subsection{Subroutine Declarations} … … 524 512 \begin{itemize} 525 513 \item 526 Subroutine declarations should be prece eded by a short comment describing what514 Subroutine declarations should be preceded by a short comment describing what 527 515 the subroutine does. These documentation comments should include a brief 528 des ription as well as other warnings, bugs, etc. as needed.516 description as well as other warnings, bugs, etc. as needed. 529 517 530 518 \item … … 542 530 543 531 \item 544 The last line before the closing brace must explicit y declare a return value.532 The last line before the closing brace must explicitly declare a return value. 545 533 \end{itemize} 546 534 … … 562 550 Each line should usually contain only one statement. Example: 563 551 \begin{verbatim} 564 x = sqrt(x2); //Correct565 i++; //Correct566 x = sqrt(x2); i++; //Avoid!552 $x = sqrt($x2); # Correct 553 $i++; # Correct 554 $x = sqrt($x2); $i++; # Avoid! 567 555 \end{verbatim} 568 556 569 557 An example of a reasonably two-statement line is: 570 558 \begin{verbatim} 571 argv++; argc--;559 $foo++; $bar--; 572 560 \end{verbatim} 573 561 where the two actions are intimately related. … … 575 563 \subsection{Compound Statements} 576 564 577 Compound statements are statements that contain lists of statements 578 enclosed in braces. See the 579 following sections for examples. 565 Compound statements are statements that contain lists of statements enclosed in 566 braces. See the following sections for examples. 580 567 581 568 \begin{itemize} … … 594 581 \subsection{return Statements} 595 582 596 A \code{return} statement with a value should not use parentheses unless they make the return value more obvious in some way. Example: 597 \begin{verbatim} 598 return; 599 600 return myDisk.size; 601 602 return (size ? size : defaultSize); 603 604 \end{verbatim} 605 606 \subsection{if, if-else, if else-if else Statements} 583 A \code{return} statement with a value should not use parentheses unless they 584 make the return value more obvious in some way. All subroutines must have an 585 explicit, non-null, return statement. Example: 586 587 \begin{verbatim} 588 return undef; # Correct 589 return; # Wrong! 590 591 return $myDisk->size; 592 593 return ($size ? $size : $defaultSize); 594 \end{verbatim} 595 596 Note: In absence of an explicit return statement Perl will return the results 597 of the last statement executed. A null return statement \code{return;} also 598 causes the result of the last statement executed to be returned. 599 600 \subsection{if, if-else, if elsif else Statements} 601 602 \code{if} statements must always use braces {} around statements and parenthesis 603 () around conditionals. 607 604 608 605 The \code{if-else} class of statements should have the following form: … … 620 617 if (condition) { 621 618 statements; 622 } els eif (condition) {619 } elsif (condition) { 623 620 statements; 624 621 } else { 625 622 statements; 626 623 } 627 628 \end{verbatim} 629 630 Note: \code{if} statements always use braces {}. Avoid the following 631 error-prone form: 632 \begin{verbatim} 633 if (condition) // AVOID! THIS OMITS THE BRACES {}! 634 statement; 635 \end{verbatim} 636 637 \subsection{for Statements} 624 \end{verbatim} 625 626 \subsection{C style for Statements} 638 627 639 628 A \code{for} statement should have the following form: 629 640 630 \begin{verbatim} 641 631 for (initialization; condition; update) { … … 644 634 \end{verbatim} 645 635 646 An empty \code{for} statement (one in which all the work is done 647 in the initialization, condition, and update clauses) should have one of 648 the following forms: 649 \begin{verbatim} 650 for (initialization; condition; update); 636 For example: 637 638 \begin{verbatim} 639 for (my $i =0; $i < 100; $i++) { 640 print "$i\n"; 641 } 642 \end{verbatim} 643 644 An empty \code{for} statement (one in which all the work is done in the 645 initialization, condition, and update clauses) should have the following forms: 646 647 \begin{verbatim} 651 648 for (initialization; condition; update) {} 652 649 \end{verbatim} … … 666 663 } 667 664 \end{verbatim} 668 An empty \code{while} statement should have one of the following forms: 669 \begin{verbatim} 670 while (condition); 665 An empty \code{while} statement should have the following form: 666 \begin{verbatim} 671 667 while (condition) {} 672 668 \end{verbatim} … … 680 676 } while (condition); 681 677 \end{verbatim} 682 683 \subsection{switch Statements}684 685 A \code{switch} statement should have the following form):686 \begin{verbatim}687 switch (condition) {688 case ABC:689 statements;690 /* falls through */691 692 case DEF:693 case GHI:694 statements;695 break;696 697 case XYZ:698 statements;699 break;700 701 default:702 statements;703 break;704 }705 \end{verbatim}706 707 Every time a case falls through (doesn't include a \code{break}708 statement), add a comment where the \code{break} statement would709 normally be. This is shown in the preceding code example with the710 \code{/* falls through */} comment. A comment is not required (or711 expected) when the fall-through is between multiple case statements.712 713 Every \code{switch} statement should include a default case, which714 should come last. The \code{break} in the default case is redundant,715 but it prevents a fall-through error if later another \code{case} is716 later (and illegally) added after the default clause.717 718 When switching on an enumerated type, if all the elements of the type719 are included in the switch a default clause should still be added (not720 all compilers diagnose missing elements). In this case, the action in721 the default clause should be to generate an error and abort.722 678 723 679 \subsection{label Statements} … … 871 827 \code{float myWidth;}\hfil\break 872 828 \hfil\break 873 \code{int ps NumOTA;}\hfil\break829 \code{int pseudo;}\hfil\break 874 830 \code{int p_psMyFiddleFactor;}\hfil\break 875 831
Note:
See TracChangeset
for help on using the changeset viewer.
