Taking over a codebase another team started: a 10-point review
Updated · 10 min read
The short answer
Before you change a line of someone else’s code, establish three things: that your organisation controls every account the software depends on, that you can build and deploy it from a clean machine, and that you can restore its data. Until those are true, every other finding is academic, because you cannot safely act on it.
Then review the rest in order: tests, dependencies and security, architecture fit, observability, documentation, cost and the exit of the previous team. Most inherited codebases should be kept and improved rather than rebuilt. A rebuild is justified when the architecture cannot support what the business needs next and changing it would cost more than starting again, which is rarer than it feels in the first week.
Why a structured review matters
Teams that inherit code tend to dislike it. It was written under pressures they did not see, in a style they did not choose, and its oddities often encode lessons about real customers and real edge cases. Joel Spolsky’s well-known essay on rewrites argues that throwing away working code throws away that accumulated knowledge, and two decades on the warning still holds, even if a blanket rule against rewrites goes too far.
A structured review replaces first impressions with evidence. It tells you what is risky now, what can wait, and whether the software can carry the business where it wants to go. It also gives non-technical stakeholders a written basis for a decision that is otherwise hard for them to judge.
The 10-point review at a glance
Work through the points roughly in this order. The first two are blockers: if they fail, fix them before anything else.
| Point | What good looks like | Warning signs |
|---|---|---|
| 1. Access and ownership | Repositories, cloud accounts, domains, app store and third-party accounts owned by your organisation, with named administrators | Accounts in a former contractor’s name; shared logins; nobody knows the domain registrar |
| 2. Build and deploy from scratch | A new engineer can build, test and deploy from written steps on a clean machine | Deploys only work from one laptop; manual server changes; missing environment variables |
| 3. Tests | Automated tests run on every change and cover the critical paths | No tests, tests that are skipped or always fail, coverage only of trivial code |
| 4. Dependencies and security | Dependencies current, scanned automatically, secrets out of the repository | Unmaintained libraries, years of skipped upgrades, keys committed to code |
| 5. Architecture fit | Structure supports the next year of planned features and load | Every change touches everything; the core data model fights the business |
| 6. Data and backups | Backups automated, restores tested, migrations versioned | Backups never restored; schema changed by hand; no record of what data is held |
| 7. Observability | Logs, metrics and alerts show what is broken before customers do | Errors found by customers; logs that are empty, or full of personal data |
| 8. Documentation and knowledge | Architecture overview, runbooks and decision records that match reality | Knowledge held in one person’s head; documentation describing a system that no longer exists |
| 9. Cost | Hosting and service costs known, attributed and proportionate | Unexplained bills; idle resources; licences nobody uses |
| 10. Team and vendor exit | Planned handover with overlap, questions answered, access revoked at the end | Abrupt exit, no handover time, former team still holding production access |
Access, builds and data come first
Start with an inventory of every account the software touches: code hosting, cloud providers, domain registrar and DNS, email sending, payment and identity providers, app store accounts, analytics, error tracking. For each one, confirm that your organisation owns it, who the administrators are, and that the recovery email and phone number are yours. Cloud root or owner accounts deserve particular care: AWS, for example, recommends protecting the root user with multi-factor authentication and not using it for everyday tasks.
Next, prove you can build and deploy. Ask an engineer who has never seen the project to build it from the README on a clean machine and deploy to a non-production environment. Every undocumented step they hit is a risk, and every secret they have to ask for should move into a proper secrets store.
Then prove you can restore the data. A backup that has never been restored is a hope rather than a backup. Restore the production database to a separate environment, check that it is complete and recent, and write down how long it took. While you are there, list the personal and financial data the system holds, because you are now responsible for it.
Tests, dependencies and security
Look at what the tests actually cover, not at a coverage percentage. The question is whether the paths that move money, change customer data or enforce permissions are tested. If they are not, writing tests around them is usually the first engineering investment, because it makes every later change safer.
Run a dependency audit and a secret scan. Outdated and unmaintained components are a long-standing source of security risk, and in the 2025 edition of the OWASP Top 10 the category has widened into software supply chain failures, covering dependencies, build systems and distribution. Note how far behind each major dependency is: a framework several major versions out of date can turn a routine security patch into a project.
Finally, check the basics of application security: how users authenticate, how permissions are enforced on the server, how input is validated, and whether secrets, keys or customer data appear in logs or the repository history. Rotate any credential the previous team had access to.
Architecture fit, observability and knowledge
Architecture is judged against the future, not against taste. Take the next year of planned features and expected growth and ask how hard each would be in the current structure. Code you would have written differently is not a finding; a data model that cannot represent the product you are about to launch is.
Observability tells you whether you will hear about problems before customers do. Google’s Site Reliability Engineering book suggests that latency, traffic, errors and saturation are a sensible minimum to monitor for a user-facing system. If none of those are measured and nothing alerts anyone, add them before you start changing behaviour.
Knowledge is the asset most easily lost in a handover. Ask the previous team for an architecture overview, the reasons behind the decisions that look strange, the known bugs and the workarounds operations staff rely on. Record the answers. A short set of decision records written during handover is worth more than a long document written afterwards.
Cost and the exit of the previous team
List every recurring cost the software creates: hosting, databases, third-party services, licences, monitoring. Inherited systems often carry resources nobody remembers creating, and some carry the opposite problem: a service on a free tier that will fail when usage grows.
The handover itself deserves a plan. Agree a period of overlap where the previous team answers questions and pairs on a real release. Make sure the contract or agreement gives you the code, the documentation and the intellectual property. At the end, revoke their access to repositories, cloud accounts and production data, and rotate shared secrets. A respectful, well-planned exit gets better answers than a rushed one.
Keep, refactor or rebuild
Once the review is done, the decision is usually clear. The table below summarises when each option fits. A rebuild does not have to be all at once: replacing a system piece by piece behind stable interfaces, sometimes called the strangler fig approach, keeps the business running while the old code is retired.
| Decision | Choose it when | Main risk |
|---|---|---|
| Keep and stabilise | The architecture fits the plan; problems are access, tests, upgrades and monitoring | Underinvesting in the fixes, so the same problems return |
| Refactor | The core is sound but some modules are tangled, slow or hard to change | Refactoring without tests, which turns improvement into regression |
| Rebuild in parts | Specific components cannot support the next stage, but the rest can | Running two systems side by side for longer than planned |
| Rebuild | The data model or platform cannot support the business, and changing it costs more than starting again | Losing hidden behaviour and edge cases; a long period with no new features |
Questions
- How long does a codebase review take?
- It depends on the size of the system and how much access you have. A small app can be reviewed in days. A large platform with many integrations can take a few weeks. Securing access and proving you can build, deploy and restore should come first regardless of size.
- Should we rebuild an inherited codebase in a newer framework?
- Not because the framework is old. Rebuild only when the current system cannot support what the business needs next and changing it would cost more than starting again. Many outdated stacks can be upgraded step by step, with tests in place first.
- What if the previous team or vendor will not cooperate?
- Secure ownership of accounts, repositories and domains first, using your contract and the providers’ own account recovery processes if necessary. Then rely on the code, the infrastructure and the data as the source of truth, and expect the review to take longer.
- What should we do on the first day after taking over?
- Confirm your organisation owns and can administer every account, rotate any credentials the previous team held, check that backups exist and can be restored, and make sure someone will be alerted if production goes down.
- Can Wideline review or take over our codebase?
- Wideline’s ongoing services cover maintenance, hosting, DevOps and continuous improvement, and a review along these lines is where we would start with any existing system. If the review shows your current team or vendor is the better home for the software, we will say so.