1. Add the "stricture" pragmas (Use strict and warnings)

use strict;
use warnings;
use diagnostics;
[download]

2. Display the contents of variables using print or warn

warn "$var\n";
print "@things\n";   # array with spaces between elements
[download]

3. Check for unexpected whitespace
• a) chomp, then print with delimiters of your choice, such as colons or balanced brackets, for visibility

  chomp $var;
  print ">>>$var<<<\n";
  [download]

• b) Check for unprintable characters by converting them into their ASCII hex codes using ord

  my $copy = $str;
  $copy =~ s/([^\x20-\x7E])/sprintf '\x{%02x}', ord $1/eg;
  print ":$copy:\n";
  [download]

4. Dump arrays, hashes and arbitrarily complex data structures. You can get started using the core module Data::Dumper. Should the output prove to be unsuitable to you, other alternatives can be downloaded from CPAN, such as Data::Dump, YAML, or JSON. See also How can I visualize my complex data structure?

use Data::Dumper;
print Dumper(\%hash);
print Dumper($ref);
[download]

5. If you were expecting a reference, make sure it is the right kind (ARRAY, HASH, etc.)

print ref $ref, "\n";
[download]

6. Check to see if your code is what you thought it was: B::Deparse

$ perl -MO=Deparse -p program.pl
[download]

7. Check the return (error) status of your commands

• open with $!

  open my $fh, '<', 'foo.txt' or die "can not open foo.txt: $!";
  [download]

• system and backticks (qx) with $?

  if (system $cmd) {
      print "Error: $? for command $cmd"
  }
  else {
      print "Command $cmd is OK"
  }
  $out = `$cmd`; print $? if $?;
  [download]

• eval with $@

  eval { do_something() }; warn $@ if $@;
  [download]

8. Use Carp to display variables with a stack trace of module names and function calls.

use Carp qw(cluck);
cluck("var is ($var)");
[download]

Better yet, install and use the Carp::Always CPAN module to make your existing warn/die complain with a stack trace:

$ perl -MCarp::Always program.pl
[download]

9. Demystify regular expressions by installing and using the CPAN module YAPE::Regex::Explain

# what the heck does /^\s+$/ mean?
use YAPE::Regex::Explain;
print YAPE::Regex::Explain->new('/^\s+$/')->explain();
[download]

10. Neaten up your code by installing and using the CPAN script perltidy. Poor indentation can often obscure problems.
11. Checklist for debugging when using CPAN modules:
• Check the Bug List by following the module's "View Bugs" link.
• Is your installed version the latest version? If not, check the change log by following the "Changes" link. Also follow the "Other Tools" link to "Diff" and "Grep" the release.
• If a module provides status methods, check them in your code as you would check return status of built-in functions:

  use WWW::Mechanize;
  if ($mech->success()) { ... }
  [download]

What's next? If you are not already doing so, use an editor that understands Perl syntax (such as vim or emacs), a GUI debugger (such as Devel::ptkdb) or use a full-blown IDE. Lastly, use a version control system so that you can fearlessly make these temporary hacks to your code without trashing the real thing.

For more relevant discussions, refer to the initial Meditation post: RFC: Basic debugging checklist

Updated: Sep 8, 2009: Added CPAN Diff/Grep tip.
Updated: Jan 11, 2011: Added Carp::Always.