Personal Perl programming 'best practices'

Blog entry for accumulating "best practice" notes.

Configuration (i.e., reading configuration files)

• use Config::General

Debugging 1

• use Perl Debugger (perldoc perldebug)
• but not with "make test" (!) -- instead, do
  

  perl Makefile.PL INSTALLDIRS=site
  

  and _then_ do "make install"
• and then write a small testing program and run it with perl -d

Debugging 2

• "make test" will display messages my program writes to STDERR
• Data::Printer's 'p' function writes to STDERR
• also works: print STDERR @my_args, "\n"
• if I don't know why "make test" is failing, insert calls to print() and Data::Printer::p() -- these will show up in the "make test" output
• if there is too much output, call it this way:
  

  $ make test 2>&1 >/dev/null | head -n 20
  

Error handling/return values

• use PARAMHASH whenever possible
• call functions like this

my @result = my_function({ MY_ARG => 'my_value' });
if ( not eval { $result[0]->is_error } ) {
   # success -- PARAMHASH in @result
   ...
} else {
   # failure
   error( $result[0]->message );
}

• read brian d foy's article entitled 'Return error objects instead of throwing
  exceptions'
• look at Dochazka::Error

Logging (i.e., to syslog)

• use Log::Fast
• look at Dochazka::Log for wrappers
• have error object write itself to log when it is created
• when using rsyslog put something like this in /etc/rsyslog.d:
  

  if      ($programname startswith 'Dochazka')
  then    -/var/log/Dochazka
  &       ~
  

Testing/unit testing

• Use Test::More, put unit tests in t directory
• Write functions with testing in mind:
  

  * generalized function _gen_XYZ to do the work
  * wrapper calling _gen_XYZ with the right arguments
  * test_wrapper for use from test harness, enabling _gen_XYZ to be called with 
    all kinds of wild arguments for triggering errors