DNR Coding (Programming) Guidelines

These code guidelines will be added to as time goes on, or (more likely) forgotten and abandoned.

TO-DO: Fix the following stupid stylesheet issue

General Guidelines

1. Don't comment your code, its unnecessary and only wastes time. If you don't know what
   
   ($script) = $ENV{'SCRIPT_FILENAME'}=~!m([^/.]*)(\.cgi)?$!;
   
   does by just looking at it, you shouldn't be working here. Whoever comes after you will just write their own code instead of fixing/upgrading yours.
2. Don't document your program/library interfaces. See #1.
3. Conserve disk space by using short, compact variable names:
   
   $atype, $ascr, $aact, $aid, $aser, $agrp, $reason
   
   are sufficiently descriptive. See #1 if you still have questions about this.
4. Use esoteric language features whenever possible. Think of it as expanding your coworkers' knowledge of the language. Education is an important part of what we do here.
5. Use map { } whenever possible--it helps raise the bar. After all, you don't want just anyone mucking around in your code. See if you can beat this one [please don't try to beat this map clause]:
   

           my @pseries = map {
               my $reltime = $_->{reltime};
               delete $_->{reltime};
               my $dspec = PDB::MakeDSpec(%{$_});
               my $v;
               if ($nninterp eq 'slwin') {
                 $v = where($inputps{$dspec}->{v},
                            $inputps{$dspec}->{gmt} >= $gmtmin-$offsetsec+$reltime*3600 &
                            $inputps{$dspec}->{gmt} < $gmt1-$offsetsec+$reltime*3600 &
                            $inputps{$dspec}->{gmt} < $gmtnow+$reltime*3600);
               }
               else {
                 $v = where($inputps{$dspec}->{v},$inputps{$dspec}->{gmt} == $gmt0+$reltime*3600);
               }
               $v;
           } @{$model->{inputs}};
   

6. To maintain individuality and job security, avoid code reviews. Everyone knows the best coders work alone.

</sarcasm>

• Maintainability overrides individual efficiency. You are part of a team.
• Document your code, preferably in the code/source itself. Use POD to document external interfaces.
• Try to leave [existing] Pharos code better than you found it:
  • Add use strict and use warnings if not present [and fix the code so it doesn't generate warnings]
  • Add/update comments/documentation
  • Call a code review
  • Use fully qualified package variable names instead of relying on use vars declarations (e.g., %PDB::ARGS instead of %ARGS).
  • Replace use vars declarations with (a) $package::variable assignment(s).
• Don't be a rear end in a top hat.

Perl

• Read the Tips for Maintainer Efficiency, from the Camel book.
• Always enable use strict and use warnings. Then write your code so it doesn't generate any errors or warnings.
• Use 3-argument open() calls.
• Use scalar variable filehandles when performing file I/O. See open() for more information.
• Use POD markup inside each module or script for documentation. This lets us use our cool web-based Pharos documentation interface.

Tips about map()

Don't do this:

   return map { "$_->[0]: <a href=$PDB::LOCATION/$_->[0]/$dates/$class>$_->[1]{'name'}</a>" }
   sort { for (@sortbys) { my $c = $a->[1]{$_} cmp $b->[1]{$_}; return $c if $c} }
   map {
      my %stna = PDB::StnAttr($NOW,$_);
      my ($lat,$lon) = split /[,\s]+/,$stna{loc};
      $stna{loc} = join "",map { sprintf("%010.5f",$_) } (999.99999-$lat),$lon;
      if ($stna{class} =~ /:tcoon:/) { $stna{class} = 'A'; }
      elsif ($stna{class} =~ /:hydro:/) { $stna{class} = 'B'; }
      elsif ($stna{class} =~ /:ccrtns:/) { $stna{class} = 'C'; }
      else { $stna{class} = 'Z' }
      [ $_, \%stna ];
   } PDB::IdList($NOW,split(/[,\s]+/, $class));

If you must create something like the abomination above, at least have the courtesy to comment your code so the person who comes after you can understand your insanity genius and why you chose to nest 3 map() calls inside of a return.

Error messages

• Anything that uses PDB has an intelligent die() that will display a webpage if it is part of an HTTP request.
• PDB::Alert() and PDB::Note() should not be used in any Web/CGI stuff.