Legacy code overdragen aan een nieuw team

Een overdracht van legacy code lukt als het oude en het nieuwe team een tijd overlappen, als het nieuwe team de code zelf kan bouwen en uitrollen voordat het iets wijzigt, en als de eerste taken klein zijn. Documentatie helpt, maar veel kennis zit alleen in de hoofden van de mensen die er nu aan werken. Plan de gesprekken met hen dus in zolang ze er nog zijn.

Breng eerst in kaart wat er is

Begin met een inventaris, nog voor de eerste overdrachtssessie. De code zelf is meestal het makkelijkste deel. Het risico zit in wat buiten de repository staat:

• servers, omgevingen en de pipeline die uitrolt
• koppelingen met andere systemen, en wie daar het aanspreekpunt is
• geplande taken, zoals een cronjob op een server waar niemand meer aan denkt
• domeinen, certificaten en accounts bij cloud- en SaaS-leveranciers
• secrets, en wie ze kent
• licenties en contracten die op naam van de vorige partij staan

Zet bij elk punt wie er nu toegang toe heeft. Met die lijst zet je later ook de toegang over.

Plan overlap met het oude team

Mijn advies is een periode van een paar weken waarin beide teams aan de code werken. Doe per onderdeel een walkthrough en neem die op. Laat daarna het nieuwe team echte tickets oppakken terwijl iemand van het oude team meekijkt. Zo komen de vragen boven die niemand vooraf bedenkt.

Houd één document bij met open vragen, zodat het oude team ze kan beantwoorden wanneer het uitkomt. Vertrekt de vorige leverancier, neem de overdracht dan op in de afspraken over het einde van het contract: hoeveel uren, welke documenten en wanneer de toegang overgaat.

Is er niemand meer om te vragen, dan zijn de git-historie, de oude tickets en de logs je bron. Dat kost meer tijd, en je planning moet daar rekening mee houden.

Wat je opschrijft

Begin bij een overdracht geen groot documentatieproject. Schrijf op wat het nieuwe team nodig heeft om zelfstandig te werken:

• een README waarmee iemand het systeem lokaal draait
• een runbook voor uitrollen en terugdraaien
• een schets van de onderdelen, de koppelingen en waar de data staat
• een lijst met bekende problemen en plekken waar je voorzichtig moet zijn
• korte notities over eerdere keuzes, zodat duidelijk is waarom iets zo gebouwd is

Laat het nieuwe team die documenten schrijven en het oude team ze controleren. Zo zie je meteen of de kennis is overgekomen, en schrijven de mensen die ermee gaan werken de documentatie zelf.

Wijzig pas iets als het nieuwe team de code kan draaien

Het eerste doel is dat het nieuwe team zonder hulp de code bouwt, de tests draait en uitrolt naar een testomgeving. Daarna gaat er een kleine wijziging via de normale weg naar productie. Pas als dat lukt, weet je dat de keten werkt.

Ontbreekt foutmonitoring, regel die dan eerst. Je wilt weten wat er misgaat voordat het nieuwe team iets verandert, zodat je daarna het verschil ziet.

Zijn er weinig tests, schrijf dan characterization tests rond de delen die je gaat aanraken. Zo'n test legt vast wat de code nu doet, ook als dat niet is wat de code zou moeten doen. Verandert het gedrag later onbedoeld, dan zie je dat meteen.

De eerste taken

Kies voor de eerste weken taken met weinig risico die toch de hele weg naar productie afleggen: kleine bugfixes, betere logging, tests toevoegen, een dependency bijwerken waar een duidelijke changelog bij zit. Begin in de eerste maand niet aan grote refactors, want het team kent de randgevallen nog niet.

Geef bij elk ticket meer context dan je bij een ingewerkt team zou doen. Hoe je dat aanpakt, staat in tickets die een remote developer begrijpt. Voor de eerste dagen van een nieuwe developer, ook los van legacy, lees je een remote developer onboarden.

Risico's die je vooraf afdekt

Sommige risico's merk je pas als het te laat is, tenzij je er vooraf naar zoekt:

• Kennis die bij één persoon zit. Laat die persoon als eerste een walkthrough doen.
• Secrets die de vorige partij kent. Roteer ze direct na de overdracht.
• Accounts op naam van de vorige partij, bij de cloud, de domeinregistratie of de app stores. Zet ze op naam van je eigen organisatie.
• Een uitrol die alleen werkt vanaf de laptop van één persoon. Zet die stap in de pipeline.
• Verouderde dependencies met bekende kwetsbaarheden. Maak een lijst en plan de updates.

Herschrijven kan later

Een nieuw team wil oude code vaak het liefst opnieuw schrijven. Werk er eerst een paar maanden mee, want pas dan weet je welke delen echt in de weg zitten. Wil je daarna vervangen, doe dat dan stap voor stap: bouw nieuwe onderdelen naast het oude systeem en verplaats de functionaliteit beetje bij beetje. Martin Fowler noemt dit de strangler fig-aanpak.

Zo werkten we bij Vision Healthcare. Een PHP-backend en een .NET Framework Forms-frontend gingen daar stap voor stap over naar .NET Core-services en een React/Next.js-frontend, zonder dat de bedrijfsvoering stil kwam te liggen.

Bronnen

• Martin Fowler, Strangler Fig Application