The failure mode is two styles
External developers who impose their own conventions on someone else's codebase leave a system with two competing approaches, which is harder to maintain than either would have been alone.
The correct posture on someone else's codebase is to write code their team would have written. Preferences are not worth the maintenance cost of inconsistency.
What works well to hand over
- New modules with a clear boundary
- Integrations with external systems
- Reporting and data work
- Specific improvements with defined scope
- The backlog of small things nobody has time for
What we need at the start
- Access to the repository and a working local setup
- Whatever documentation exists, however thin
- An hour with someone who knows the system
- The coding conventions, written or demonstrated
- Clarity on how work gets reviewed and deployed
The local setup is frequently the longest part. A codebase that takes two days to run locally is a warning sign in itself.
Review both ways
Their team reviews our work, and we are happy to review theirs. That keeps the codebase consistent and it transfers knowledge in both directions.
It also means nothing lands that their team does not understand, which is the thing that matters after we leave.
Leave it documented
| Handover item | Why |
|---|---|
| What was built and why | Context is lost otherwise |
| Any decisions and trade-offs | So they are not re-litigated |
| Tests covering it | Confidence to change it |
| Anything deliberately deferred | Known debt, recorded |
| Who to ask afterwards | A named contact |