CIS 480 - Perl in Depth - Class Coding Standards and Style Guidelines

CIS 480 - Section 2
Perl in Depth
Fall 2004

In general, it is expected that you learned the tenets of basic, reasonable style in your previous programming courses. This is, thus, not an exhaustive list. If you are not sure if a practice you follow is good style, please ask!

What follows are a selection of points that I have noticed in homeworks or that are Perl-specific. This list WILL be added to during the semester; I will change the last-modified date whenever it is updated.

Programs can lose points for poor style.

• when you open a filehandle in a script...
  • ...explicitly indicate its purpose with <, >, or >>, followed by a blank, before the filename;
  • ...you are expected to explicitly close it within that script, also.
  
  
• some style guidelines relating to subroutines :
  • precede each subroutine with a brief block comment summarizing what the subroutine does (this is SEPARATE from the overall-script block mentioned in the General Style section below).
  • a subroutine should not, in general, use global variables --- use arguments and lexical variables (my variables) instead.
  • "name" your parameters within a subroutine as was was discussed in lecture and in the course reading.
  • if a subroutine deliberately returns a value, it should be returned using the keyword return in an appropriate fashion.
  
  
• specify that warnings be turned on in the script's first line:

  #!/usr/bin/perl -w
  

• for now, (starting with HW #3), begin each script with the following:

  #!/usr/bin/perl -w
  ###480-author: yourLastName
  ###480-scriptname: yourScriptName
  

  ...and then follow this with a block comment containing at least a brief description of the script, your name, and the date that you last modified that script.
• for each subroutine, precede it with a block comment that includes at least a brief description of the purpose of that subroutine
• you should always include explanatory comments for anything unusual or likely to be confusing or misunderstood.
  
  
• identifiers are expected to be descriptive
  
  
• curly braces are placed on their own line, not at the end of a line. They are placed even with the beginning of the block that they define. Thus, these all meet the course style standards:

      if ($name eq "George")
      {
          print "Hello, $name!\n";
      }
  
      sub whatever
      {
          # contents
      }
  

• blank lines should be used between subroutines and between logical sections of scripts for readability; however, do not overuse blank lines, or it blunts their impact (and do not put a blank line after EVERY line!)
  
  
• indentation is vital to readability.
  • you are expected to indent by a large enough quantum that your indentation is VISIBLE --- for this class, you must indent by 4 or more spaces.
    
    
  • once you decide on how much you are going to indent, you are expected to consistently indent by that amount (not indenting by 4 for one loop and 6 for the next, for example)
    
    
  • bodies of blocks are *always* indented.
    
    
  • if two statements are in sequence, they are indented evenly with one another:

            $first = $value;
            &second($first);        # sequentially follows $first = $value
         
            if ($blah)
            {
                &action1();
                &action2();	        # sequentially follows &action1()
            }
        
            &afterIfAction();       # sequentially follows if statement
    

  • long lines should be continued on the next line, indented by a reasonable/visible amount (this might be one indentation quantum, or perhaps to line up with a quote or parenthesis in the previous line, according to your taste):

            print "The rain in Spain stays mainly oh mainly oh so so mainly ",
                "in the plain\n");
     
            or
    
            print "The rain in Spain stays mainly oh mainly oh so so mainly ",
                  "in the plain\n");
    

  • Avoid very long lines --- what may look fine for you in a tiny type and a large window may not look fine to someone using a more-standard setting. I'll judge based on how it looks in pine; so, when in doubt, look at how your CC'd copy looks in pine!
    
    
  • Indent each comment so that it is even with the line directly following it:

            # say what, don't mimic the code following
    
            &actionDesired($item);