Devel::ModInfo (and the tools it comes with) might also be useful (though I've not used them).

There are also useful B:: modules like B::Xref, but but they're more useful for developing tools like the forementioned modules (which might be what you're after).

I have found several utilities to be helpful for just this sort of thing.

When I asked something similar in the FullPage Chat, castaway pointed me in the direction of podgen, which will jump-start the process of commenting your monolith.

DoxyFilt* is a filter than allows the source-to-documentation tool Doxygen to understand Perl. Once you have your source commented, documentation becomes absurdly easy.

Perl::Tidy helps clean up your source and make it more readable. Perl Builder and ActiveState's Komodo may also have some helpful options or utilities.

Update: Seeking advice about learning another's code and Reverse Engineering Perl Tool? also contain excellent suggestions.

HTH,

* Update: 2005-12-28 Kudos to both john_oshea and tfrayner for alerting me to the fact that my link above has been rendered usless by the foul creatures known as spammers... I have found what appears to be a good link to obtain DoxyFilt; the most recent version seems to be from August 24, 2005: Doxygen-0.84.tar.gz. Thanks again, guys!

Find out who wrote the code and be nice to them. Offer to buy them lunch. Pick their brains. Learn all about them. Were they accomplished programmers or newbies when they wrote the system? Are they careful or slapdash? Are they domain experts? What was the political climate when they wrote the system? No matter how well documented a system, there is always extra important information and ideas available only inside the original designer's head.

As you understand a section of code, comment it. If you see something that looks dubious, mark it with XXX, say. You can come back to these XXXs when you better understand the system as a whole and have more time.

Whenever you find a bug in the system, write a test for it. Grow the test suite over time. I assume (like me) you will not be given time to write a comprehensive test suite before taking over maintenance of the code base.

See also Analyzing large Perl code base. and the book Perl Medic by Peter Scott.

Perl Medic

It's a book about rescuing bad Perl code from itself. It has all kinds of good advice for you. Read it.

-sam

Drop everything. Run to the bookstore. Buy: Perl Medic It's a book about rescuing bad Perl code from itself. It has all kinds of good advice for you. Read it.

Seconded (I'd mentally begun a reply with "Run, don't walk, ..." just before i read this node :-)

See also Refactoring: Improving the Design of Existing Code (ISBN 0201485672). It may not be exactly applicable, but it outlines a very good mindset and process for improving existing code (e.g. Test, test, test; make small incremental changes; test, test, test; lather, rinse, repeat).

You might developing something along those lines yourself (since I foolishly wrote my program at work, it is,of course, copyright by my company, so I can't post code for you).

Learn to use the perl debugger: it's handy. It will let you execute arbitrary perl code to see what it does, single step through functions, stop at certain lines, and so forth. While you just can't "go back" to a previously executed line in the debugger, you can often just copy the line, and single step through it. This is most useful for function calls that have gone awry.

eg. Suppose the line $x = foo($y) returns the wrong thing. Just type s foo($y) into the debugger, and single step through foo() until you find the call in foo() that's wrong, say bar(). Then single step through bar(), and so on. Keep chasing your way down the call stack until you find the bug.

The debugger certainly doesn't default to printing each subroutine that's called, but it can be made to do it by writing some custom debugging code. There may be CPAN modules that will do this for you, as well.

Do a 'perldoc perldebug' for the standard debugger documentation; do 'perldoc perldebguts' to learn how to reprogram the internals of the perl debugger to make it do other useful things.
--
Ytrew Q. Uiop

I think I'm going to give it a try in my own day-to-day CGI debugging.

CGI::Debug just dumps information to the browser.

What you probably _really_ want (esp for the file upload stuff) is CGI::Capture, which is the anally-retentively-accurate record and playback module for CGI calls.

Add the CGI::Capture line to the script pointing at a file, and after you do the first call to the CGI, it will replay the same request over and over, and if you run the CGI script from the console it will do a whole bunch of checks to make sure you are doing the debugging as accurately as possible.

And because it works at the filehandle level, it isn't even dependant on CGI. You should be able to use it with anything.