A zip file and a login
Maybe the developer left, the agency went out of business, or you bought a company and its software came with it. Either way you have a repository (or a zip file), some server credentials, and no README worth reading. Nobody can tell you how to set up a local copy, what the scheduled jobs do, or why there are three tables called customers.
The system works, mostly. People depend on it. You need to change it, and every developer who looks at it goes quiet.
Why undocumented code is so risky to touch
The code itself is only part of the system. The rest lives in places that are hard to see from reading files.
- Configuration and secrets sit on the server, not in the repository.
- Scheduled jobs and scripts run from crontab or a task scheduler that nobody checks.
- Business rules are hidden in database triggers or stored procedures.
- Integrations depend on accounts, webhooks and IP allow-lists set up by hand years ago.
- The server has hand-made fixes that were never copied back into the code.
Change something without knowing these exist and the failure appears somewhere unrelated, often days later.
The cost of working blind
| Symptom | Consequence |
|---|---|
| Nobody can build it locally | All changes are made on the live server |
| No tests | Every change risks breaking something unseen |
| Unknown integrations | Changes break things outside the system |
| Hidden business rules | Figures change and nobody knows why |
| Developer reluctance | Changes cost more because everyone is cautious |
The last row is expensive in a quiet way. Estimates for small changes grow because developers build in time for surprises, and they are right to.
There is also the risk of the server itself. If the only working copy of the system is the live machine, a disk failure or a hosting account problem takes away not just the service but the only place its configuration exists. Rebuilding from a repository that was never complete is much harder than it sounds.
And hiring gets harder. Good developers ask about the codebase in interviews. An honest answer of no documentation, no tests and no local setup puts off exactly the people you would want.
How we take over undocumented code
- Secure it. Put the code in a repository your business owns, copy server configuration safely, and list every account and credential in use, rotating any that previous people had.
- Get it running outside production. We rebuild the setup locally and on a staging server, writing every step down as we go. This alone often reveals most of the hidden dependencies.
- Map it. A short architecture document covers the main components, the database, scheduled jobs, integrations and where data flows. Diagrams are kept simple and live in the repository.
- Capture current behaviour with tests. Before changing anything important, we write tests that record what it does today, including the odd behaviour people depend on.
- Document the business rules we find, especially those buried in the database, and confirm them with your staff.
- Change it in small steps, with those tests and staging in place, so each change is checked before it goes live.
Documentation is written as a by-product of this work, not as a separate project. That keeps it accurate, because it is written by people who just did the thing it describes.
After the takeover
The system builds on a clean machine by following the README. The main parts, integrations and scheduled jobs are written down. Critical behaviour has tests, so changes can be checked. Your team, or anyone you bring in later, can pick it up and make changes with ordinary caution rather than fear.
Does this sound familiar?
- You have code but no reliable setup instructions.
- Changes are made directly on the live server.
- Nobody can explain what all the scheduled jobs or scripts do.
- Developers quote large estimates for small changes.
- You inherited the system from someone who is no longer available.