Programming Style Requirements for BIOS 546

One goal of this course is to teach you how to good solid computer code: your code should not only function as required, but it should also be easy to read. If you use your programming knowledge in the future, you will find that it's hard to remember how a progam works months or years after you wrote it. Also, others may need to read and modify your code, and their happiness will be greatly increased if they can understand it easily.

So, for the purposes of this course, I require that all submitted programs follow the following requirements:

• Your program should be run with the "-w" (warning) flag. Thus, your first line should be: "#! /usr/bin/perl -w". I expect that your program will run with no error or warning messages appearing.
• You must use the "strict" pragma. Thus, near the top of your program the line "use strict;" must appear. The main effect of this statement is to require that you declare your variables. This is done with the "my" operator: "my $var;" declares the $var variable. You can also assign a value to the variable while you declare it: "my $var = 17;" for example. The "strict" pragma causes your variables to be limited in scope to the block in which they were declared (or global scope if declared outside any block). It checks for a few other things too.
• All variables must have meaningful names. Thus, "$sequence", "$count", "@names", and "%codons" are all good names, but "$x" and "@asdf" are bad names. Especially, don't use "$a", "$b", "$1", "$2", "$!" or any similar name, because these variables have special meanings in Perl. In general, using a single symbol for a variable name is a bad idea. Exception: You can use "$i", "$j", "$k" and similar variables as loop counters: "for (my $i = 0; $i < 10; $i++) " is a very standard and acceptable construction.
• Use white space liberally. You should write things like "$num = 4;" and avoid running it all together: "$num=4;" is bad style. Also, leave blank lines between sections of code to make the sections easier to pick out visually.
• Use consistent indentation Blocks within other blocks need to be indented. There are many styles for this, and I don't require that you use any particular style. However, you must be consistent in your use. I make the following non-binding suggestions:
  • Put the opening "{" (curly brace) for a block on the same line as the statment that opens the block. "if ($black eq $white) {" for example.
  • The closing brace "}" should be on a line by itself, aligned vertically with beginning of the statement that opened the block.
  • An exception to the above rule: if you have an "elsif" or "else" statement it can be on the same line as the brace closing the previous block: "} else {" for example.
  • The contents of a block should indented 4 spaces from the block opening statement and the block closing curly brace.

  Example of block indentation:

  if ($number == 3) {
      do something useful;
      and someting else;
  } elsif ($number > 3) {
      foreach $item (@list) {
          do a different thing repeatedly;
          maybe count it too;
      }
  } else {
      do yet another thing;
  }
  
  

• Put header information on each program. At the top of each program, just beneath the "#! /usr/bin/perl -w" statement, you should write a paragraph giving the name of the program, describing what the program does, what its inputs and outputs are, and any other useful comments about it. The header should also give your name and the date.
• Put comments on sections of code and important lines. Perl comments are anything on a line following a "#". Unlike C, Perl has no way to make multi-line comments: you need to start each comment line with a "#". Use comments to describe what is going on in the code. Line and section comments are the most important factor in being able to understand your (or someone else's) code. It is essential that you use them.