Perl Scripts ·
How to Document Legacy Perl Code Before You Change It
By Manu Mathew, Technical Lead Engineer · Published 29 October 2026 · Last updated 29 October 2026
A request comes in to change an old Perl system. It might be a new report, a fix for a billing rule or an upgrade to a newer server. Then someone asks the awkward question: what else does this code do, and what might break?
If nobody can answer with confidence, the safest first step is not a code change. It is to document legacy Perl code well enough that the next change is a decision rather than a guess. This post covers what to record, how to gather it quickly, and how to keep the notes useful.
Quick answer
To document legacy Perl code before you change it, record what the system does from the outside first: its entry points, inputs, outputs, scheduled jobs and the data it touches. Then map what it depends on, note the risky areas and keep it all in a short written guide stored next to the code.
Why document legacy Perl code before changing it?
Because a change you can’t explain is a change you can’t safely test, review or undo.
Older Perl systems often carry years of business rules that were never written down. The people who built them may have moved on. The code still works, but the reasons behind it live only in the code itself.
Writing things down first gives you three practical benefits:
- Fewer surprises. You find the cron job, the email or the file another system reads before a change breaks it.
- Better estimates. It is easier to plan work when you know how far a change will reach.
- A safety net to build on. The notes tell you which behaviour to protect with tests.
What should you write down first?
Start with what the system does as seen from outside, not with how each line works.
This is the order I usually follow:
- Purpose. In two or three sentences, what the system is for and who relies on it.
- Entry points. Every way it starts: web scripts, command-line scripts, scheduled jobs, queue workers.
- Inputs and outputs. Forms, files, emails, reports, API calls and the format of each.
- Data. Which databases and tables it reads and writes, and any files it keeps.
- Platform. Operating system, Perl version, web server and the libraries the code loads.
- Secrets and access. Where passwords and keys are stored and who can read them. Record the location, never the secret itself.
- Known quirks. Anything people already work around, such as a report that must run after midnight.
You don’t need every answer on day one. A list of open questions is part of good documentation too.
How do you find out what an old Perl application depends on?
Search the code for what it loads and what it reaches outside itself, then confirm the findings on the running server.
A quick first pass at the modules each file loads (tested with Perl 5.40):
perl -ne 'print "$ARGV: $1\n" if /^\s*(?:use|require)\s+([A-Za-z][\w:]*)/; close ARGV if eof' \
$(find . -name '*.pl' -o -name '*.cgi' -o -name '*.pm')It prints one line per file and module, such as ./order.cgi: DBI. It skips quoted require lines, so search for those separately. Then look for places where the code reaches outside itself:
grep -rnE 'open\s*\(|`|system\s*\(|exec\s*\(' --include='*.pl' --include='*.cgi' --include='*.pm' .These searches are a starting point, not a full answer. Older code may build file names or commands at run time, so also check:
- The crontab and any scheduler, for jobs nobody mentioned.
- Web server configuration, for which scripts are reachable and under which addresses.
- Logs, for which scripts actually run and how often.
- The database, for tables the code writes to but nothing seems to read.
perl -V on the live server shows the exact Perl version and its library paths, which often differ from a developer’s machine.
What does useful documentation look like?
A short guide, stored with the code, that a new developer can read in under an hour.
Long documents tend to go out of date. A few focused pieces usually work better:
| Document | What it covers | Where it lives |
|---|---|---|
| README | Purpose, how to run it, who to ask | Top of the repository |
| System map | Entry points, data, other systems | A single page or diagram |
| Run book | Scheduled jobs, restarts, common failures | Next to the deployment notes |
| Module notes | What a tricky file does and why | POD inside the file |
| Open questions | What is still unknown or uncertain | A short list, reviewed regularly |
Perl’s own documentation format, POD, lets you keep notes inside the code files themselves, and perldoc can display them. Notes that sit beside the code are more likely to be updated when the code changes.
How do documentation and tests work together?
Documentation says what the system should do, and tests check that it still does it after a change.
Once you have recorded the important behaviour, turn the riskiest parts into tests: a known input and the output the current system produces. My post on testing legacy Perl code before you change it covers that step in more detail.
Where the documented behaviour looks wrong, write that down rather than fixing it straight away. Sometimes another system depends on the odd result, and the business needs to decide before anyone changes it.
How do I document a legacy Perl system with a team?
I start read-only, write as I go, and check my understanding with the people who use the system.
- Read-only first. I read the code, configuration and logs without changing anything on the live system.
- Notes in plain language. The system map and open questions are written so that non-developers can follow them.
- Short check-ins. I confirm findings with the people who use the system, because they often know the quirks the code hides.
- Handed over, not kept. The documents go into your repository, so your team owns them after the work ends.
Whether you are looking for a Perl developer in India, a Perl developer in Kerala or someone nearer to you, ask how they will learn the system before changing it. A clear answer to that question says a lot about how carefully the work will be done.
Frequently asked questions
How long does it take to document a legacy Perl application?
It depends on how much code there is, how many systems it talks to and how much is already written down. A first system map and list of open questions can often come quickly. Deeper notes on tricky areas are usually added as each part is worked on.
Should we document everything before making any change?
No, document enough to understand the area you plan to change and what it touches, because recording the whole system in detail first often delays useful fixes. Grow the documentation with each change, so it stays accurate and focused on what matters.
Can AI tools help document old Perl code?
They can help summarise a file or suggest what a function does, which saves reading time. Their output still needs checking against the running system, because they can misread older Perl idioms or guess at business rules. Treat their notes as a draft for a person to verify.
What if the original developers are no longer around?
That is common with older systems. Start from the outside: what the system receives, what it produces and what data it changes. Logs, the database and the people who use it every day fill in much of what the original developers would have told you.
Where should we keep the documentation?
Keep it in the same repository as the code, so changes to both can be reviewed together. Use a README for the overview, POD inside tricky files and a short run book for operations. Avoid scattering notes across email threads and personal folders, where they are easily lost.
Need help understanding an old Perl system?
If you have Perl code that needs documenting, fixing, extending or upgrading, I’m happy to take a look. The Perl development page covers the kinds of work I take on and how remote projects run.
You can reach me through the contact section or email me at manu@manu.co.in. A few lines about the system and what you need is a good start.