I found in my archives a translation of the old and well-known, but not lost, brian d foy tutorial on debugging Perl programs.

(Translation brian's_guide.pod )

')
Follow this guide and take care of your nerves .

My debugging philosophy

I believe in three things:

1. Nothing personal

Forget about the authorship of the code. You can consider yourself an artist, but even great artists did a lot of bullshit. All the code is nonsense, that is, my code is nonsense, and yours too. Get over it. If there is a problem, then the first thought should be "there is something wrong with my rubbish code." So you will not be found guilty of Perl. Nothing personal.
Forget about how you do something. If your approach worked, you would not read it. There is nothing wrong with that, you just need to develop. We will all be there.

2. Personal responsibility

If there is a problem with the script, then this is only your problem. You need to do everything possible to solve it. Remember that everyone else has their own scripts, I mean their problems. Do your homework and try to do it yourself before jerking someone else. If you honestly tried everything in this guide, but did not solve the problem, then it's time to disturb others.

3. Approach needs to be changed

Correct everything so as not to meet again with the same problem. Perhaps it is in the way you program, and not in that . Change the approach to make your life easier. Do not force Perl to adapt to you, because it will not. Adjust to Perl. It is just a language, not a way of life.

My method

Does your script compile in strict mode?

If you do not use strict mode, turn it on. Perl-gurus are gurus because they use strict , it allows you to solve other problems, learn new things and upload working modules to CPAN .
The strict mode is enabled by the strict pragma:

  use strict; 

From the command line, this can be done using the -M option:

  perl -Mstrict script.pl 

After that, perl may bother you, but after a couple of weeks of programming in strict mode, your code will get better, it will take less time to catch simple errors, and maybe there will be no need for this manual.

What kind of warning?

Perl will warn of many suspicious constructs. Turn on warnings and help Perl help you.
Use the -w parameter in the line with the interpreter:

  #! / usr / bin / perl -w 

You can enable warnings from the command line:

  perl -w script.pl 

You can use lexical warnings with all sorts of interesting features (details are in perldoc warnings ).

  use warnings; 

If the warnings are not clear, see the detailed version in perldoc perldiag or use the diagnostics pragma:

  use diagnostics; 

Solve the first problem first!

As soon as perl gave you error messages or warnings, eliminate the first one, and then see if the rest of the messages are displayed - the first problem can be the cause.

Look at the code before the line referenced by the error message!

Perl issues warnings after feeling uneasy, but not before. By the time perl is concerned, the problem has already arisen, and perl is, in fact, already after the problem. Take a look at a couple of expressions up to the line under the number indicated in the warning.

Does it mean what you think?

Do not guess! In fact, check the value before using it in an expression. The best debugger in the world is print .

  print STDERR "Value --- [$ value] \ n"; 

I enclose $value in brackets to see all spaces or line breaks at the beginning or end.
If I am dealing with something other than a scalar, I use Data::Dumper to output the structures.

  require Data :: Dumper;
 print STDERR "Hash ---", Data :: Dumper :: Dumper (% hash), "\ n"; 

If the meaning is not what you think, go back a few steps and try again. Repeat until you find the point at which the value ceases to be expected.
You can also use the built-in perl debugger by running perl with the -d option. Details are in perldoc perldebug .

  perl -d script.pl 

There are other debuggers or development environments like ptkdb (a graphical debugger based on Tk) or Komodo (IDE ActiveState based on Mozilla).

Are you using the function correctly?

I have been programming in Perl for quite some time, but I still look at perldoc perlfunc almost every day. Something I just can not remember, and sometimes because of lack of sleep, all feelings leave me, and it is not clear why sprintf() does not print on the screen.
You can find a separate function with the perldoc command using the -f option:

  perldoc -f function_name 

If you are using a module, check the documentation to make sure that you are using it correctly. This is done with perldoc:

  perldoc Name :: Module 

Do you use the required special variable?

And again, I look at perldoc perlvar all the time. No, not so often, since I found the “ Perl Pocket Reference ” book more convenient.

Do you have the correct version of the module?

Some modules change behavior from version to version. Do you have the version of the module you are thinking about? You can find out the latest version with this perl one-liner:

  perl -M Name :: Modules -le 'print Name :: Modules-> VERSION'; 

If you do not see most of the documentation on the local machine, but on http://www.perldoc.com/ or http://search.cpan.org/ , then you will most likely find differences in the text versions.

Did you make a small test case?

If you are trying something new, or part of the code works strangely, write the shortest possible program that executes only that code. This will exclude from consideration most other things. If a small test program does what it needs, then the problem is most likely not in that code. If the program does not work correctly, then you may have found a problem.

Did you check the medium?

Some things depend on environment variables. Are you sure that they are installed correctly? Does your environment match the one in which the program works? Remember that CGI programs or cron tasks can see environments that are different (especially on different machines) from what is available from your interactive shell.
Perl stores the environment in %ENV . If you need one of these variables, be prepared to provide a default value if the variable does not exist, even for the duration of the test.
If there is still a problem, check the environment:

  require Data :: Dumper;
 print STDERR Data :: Dumper :: Dumper (\% ENV); 

Looking at google ?

If you have a problem, then maybe someone had the same. Look in Google Groups , did anyone write about this in comp.lang.perl.misc . The difference between people asking questions in USENET and answering them is the ability to effectively search on Google Groups.

Profiler used?

If you want to scroll through slow program sections, have you used a profiler? Let Devel::SmallProf do the hard work for you. He counts the amount of execution of the line of code and the duration of the process, and then shows a beautiful report.

Which test does not work?

If you have a test suite, which test doesn't work? You should be able to find the error very quickly, as each test executes only a small part of the code.
If there is no test suite, why not do it? I do not ask you to write a couple of tests if the script is really small or one-time. But everything else really benefits from a few test scripts. Test::Harness makes it so simple that you have no excuse not to use tests. If you don’t have time, you may be spending too much on debugging scripts without tests. MakeMaker, in the end, is needed not only for modules.

Thinking out loud?

Explain the problem out loud. Really speak the words.
For a couple of years I had the pleasure of working with a very good programmer who could handle almost everything. When I got stuck on something, I went to his table and started explaining the problem. Usually, there were no three sentences either, as I was interrupted: “forget, I understood” (but he almost always found a solution).
Since you will probably have to do this very often, I advise you to choose something like a plush toy as your Perl therapist and not annoy your colleagues. I have a little bear on my desk, and I explain the problems to him. My girlfriend does not even pay attention when I talk to myself.

Does the problem look different on paper?

You stared at the computer screen, and, perhaps, on another medium, things will look different. Try to look at the printout of the program.

Watched a TV show today?

Seriously. Take a break. Stop thinking about the problem for a while and let the brain rest. Go back to the problem later, and the solution may be obvious.

Have you diminished your conceit?

If you have not finished yet, the problem may be psychological. You can be emotionally attached to a separate part of the code, so do not change it. You may also think that everything is wrong except for you. Then you are not taken seriously with the most likely source of error - yourself. Don't miss anything. Check it out.