Jour 45 Day 45 · vendredi 9 octobre 2026 Friday 9 October 2026 Méthodo Fondamental

Aborder une codebase inconnue Approaching an unknown codebase

Premier jour de stage : 150 000 lignes que tu n'as jamais vues. La méthode pour explorer, poser les bonnes questions et livrer une première PR sans rien casser — une compétence que les recruteurs testent directement. First day of your internship: 150,000 lines you have never seen. The method to explore, ask the right questions and ship a first PR without breaking anything — a skill recruiters test directly.

L’essentiel

Premier jour de stage : un accès au repo, 150 000 lignes écrites par des gens que vous ne connaissez pas, et un ticket. Le réflexe naturel — tout lire pour « comprendre avant d’agir » — est exactement le mauvais. Personne ne connaît toute la codebase, pas même le lead qui est là depuis cinq ans. Les développeurs efficaces ne comprennent pas tout : ils savent trouver vite, avec une carte mentale grossière et des techniques de recherche précises.

La compétence évaluée en entretien n’est donc pas « connaître » mais explorer : par où on entre, comment on suit un fil, à qui et comment on demande, comment on livre un premier changement sans risque. C’est l’une des rares questions où le recruteur évalue directement ce que vous ferez la première semaine.

Trois principes tiennent lieu de méthode :

Faire tourner avant de lire. Une app qui tourne en local est un terrain d’expérimentation ; du code lu à froid, c’est de la fiction.
Suivre un fil, pas la pelote. Une requête, une feature, un bug — de bout en bout. La carte se construit fil après fil.
Le code ment moins que la doc. README obsolète, wiki abandonné : les tests et le git log sont les seules sources toujours à jour.

Comment ça marche

Jour 1 : cloner, lancer, noter. Clonez, suivez le README à la lettre, et notez chaque étape manquante ou fausse : la variable d’environnement non documentée, la version de Node implicite, le service qui doit tourner à côté. Ces notes valent de l’or (voir plus bas). Objectif de la journée : l’app tourne en local et vous savez lancer les tests. Rien d’autre.

Ensuite : chercher les points d’entrée. Toute codebase a des portes : le main(), le fichier de routes, les handlers d’événements, les crons. Depuis une porte, suivez une requête de bout en bout — le geste qui rapporte le plus de compréhension par minute :

HTTP POST /orders
      │
      ▼
routes/orders.ts          ← la porte d'entrée
      │
      ▼
OrderController.create()  ← validation, auth
      │
      ▼
OrderService.place()      ← la logique métier vit ici
      │
      ▼
OrderRepository ────────▶ PostgreSQL

Un aller-retour comme celui-là vous apprend l’architecture réelle (pas celle du wiki) : les couches, les conventions de nommage, où vit la logique métier.

Les réflexes selon la situation :

Situation	Réflexe
« Où est géré X ? »	`rg` sur une chaîne visible (message d’erreur, label UI)
« Ce fichier fait quoi ? »	Ses tests d’abord, puis `git log --follow`
« Ce comportement est-il voulu ? »	S’il est testé, il est voulu
« Qui peut m’aider sur ce module ? »	`git shortlog -sn -- chemin/`
« Par où entre cette requête ? »	Fichier de routes / point d’entrée du framework
« Mon grep ne trouve rien »	Chercher la chaîne exacte de l’erreur, pas le nom supposé

Une session d’exploration typique, en partant d’un message d’erreur :

# Point de départ concret : une chaîne visible dans l'API
rg "insufficient stock" -l
#   → src/services/order.service.ts

# Qui utilise ce service ? (la carte des dépendances)
rg "OrderService" -t ts -l

# L'histoire du fichier : les commits racontent le pourquoi
git log --follow --oneline -15 -- src/services/order.service.ts

# Qui a le contexte ? (à qui poser LA bonne question)
git shortlog -sn -- src/services/order.service.ts

# La spec vivante : les tests décrivent le comportement attendu
rg "insufficient" src --glob "*.test.ts"

💡 Le README que tu écris en onboardant — pendant vos deux premières semaines, vous êtes la seule personne de l’équipe à voir la codebase avec des yeux neufs. Chaque étape de setup manquante, chaque convention implicite que vous notez devient une PR de doc que l’équipe ne pouvait plus écrire elle-même. Souvent la meilleure première contribution : utile, sans risque, et elle prouve que vous transformez votre confusion en valeur.

Concepts clés à maîtriser

Cartographie progressive : l’objectif n’est jamais « tout comprendre » mais tenir une carte à jour — les 5-6 modules principaux, leurs frontières, qui parle à qui. Le détail se charge à la demande, quand un ticket vous y emmène.
Les tests comme documentation : un test décrit le comportement attendu, avec des exemples exécutables, garantis à jour (sinon la CI est rouge). Lire order.service.test.ts avant order.service.ts : cas nominaux et cas limites y sont listés.
Git comme mémoire de l’équipe : git log sur un fichier raconte pourquoi il existe ; git blame sur une ligne étrange remonte au commit (et souvent au ticket) qui l’a introduite ; les fichiers les plus modifiés sont les fichiers chauds, ceux qui concentrent l’activité — et les bugs.
Poser des questions intelligemment : timeboxer la recherche (30-45 min), puis demander en montrant le chemin parcouru : « je cherche où X est validé ; j’ai regardé le controller et grep “X”, je vois la validation du format mais pas la règle métier — elle vit où ? ». Cette forme prouve l’effort, cadre la réponse, et personne ne la trouve pénible.
La première PR : petite et sûre : une typo dans la doc, une étape de setup manquante, un test sur un cas limite non couvert. Le but n’est pas de briller mais de traverser tout le pipeline (branche, PR, review, CI, merge, déploiement) sur un changement dont la review prend deux minutes.
Le debugger comme outil d’exploration : un breakpoint sur le handler + la call stack = l’architecture réelle en une exécution, là où la lecture statique peut mentir (injection de dépendances, indirections).

🎤 En entretien — « Comment tu t’y prendrais dans notre codebase ? » est une vraie question, parfois posée devant un vrai écran. Réponse gagnante : dérouler la méthode (lancer l’app, lire les tests du module concerné, suivre une requête, git log des fichiers chauds) plutôt que promettre de « tout lire ». Bonus : demander « vous avez une doc d’onboarding ? Sinon, ma première PR sera de la commencer ».

En entretien

« On te lâche lundi dans notre codebase de 200k lignes : tu fais quoi la première semaine ? » — Jour 1 : cloner, faire tourner, lancer les tests, noter tout ce qui manque au README. Jours 2-3 : suivre une requête de bout en bout pour comprendre les couches réelles, repérer les fichiers chauds avec git log. Fin de semaine : une première PR minuscule (doc de setup, test manquant) pour traverser le pipeline complet. Je ne cherche pas à tout comprendre : je construis une carte, module par module, tirée par les tickets.

« Tu es bloqué sur un bout de code incompréhensible, tu fais quoi ? » — Ses tests d’abord (le comportement attendu), puis git blame → le commit → le ticket (le pourquoi). Si ça ne suffit pas : timebox, puis question à l’auteur (retrouvé via blame/shortlog) en montrant ce que j’ai déjà exploré. Rester bloqué deux heures en silence coûte plus cher à l’équipe que demander au bout de 30 minutes avec le contexte.

« C’est quoi une bonne première PR ? » — Petite, sûre, utile : correction du README de setup, test sur un cas limite, typo. Elle valide que je sais dérouler tout le workflow de l’équipe (branche, conventions de commit, review, CI) sur un changement à risque nul. La grosse feature viendra quand la carte sera fiable.

« À quoi te servent les tests dans du code que tu découvres ? » — De documentation exécutable : ils listent comportements attendus et cas limites, et ils sont à jour par construction. Ils servent aussi de harnais : avant de modifier du code que je maîtrise mal, un test qui capture le comportement actuel me protège des régressions.

« Le README dit X mais le code fait Y : tu crois qui ? » — Le code, toujours : c’est lui qui tourne en prod, le README date. Mais l’écart est une info en soi : je vérifie avec git log si Y est récent, je demande si le changement est voulu, et la correction du README devient une PR.

Pièges & idées reçues

⚠️ Le refactoring précoce — le code qui vous semble « nul » la première semaine a souvent une raison d’être que vous ne voyez pas encore : contrainte métier, bug historique, dépendance externe. C’est la barrière de Chesterton : on ne retire une barrière qu’après avoir compris pourquoi elle est là. Proposer un grand refactoring en semaine 1 est le signal junior par excellence.

« Je dois tout comprendre avant de toucher quoi que ce soit » — non : la compréhension vient en faisant. Un ticket bien choisi apprend plus que trois jours de lecture passive.
Rester bloqué en silence pour « ne pas déranger » : au-delà de 30-45 minutes de recherche réelle, ne pas demander coûte plus cher à l’équipe que demander.
L’inverse aussi : demander avant d’avoir cherché grille votre crédit. La question doit montrer le chemin déjà parcouru.
Faire confiance à la doc plutôt qu’au code : wiki et README dérivent ; tests et git log ne mentent pas.
La première PR ambitieuse : 800 lignes en semaine 1 = review interminable, risque maximal, mauvais signal. Petit, sûr, mergé.

Pour aller plus loin

Understand Legacy Code — le blog de Nicolas Carlo, entièrement dédié au sujet
Working Effectively with Legacy Code (Michael Feathers) — le classique : harnais de tests, seams, modifications sûres
ripgrep — apprendre rg à fond, l’outil n°1 de l’exploration
git log et git blame — les options qui changent tout : --follow, -S (pickaxe), -L
The Programmer’s Brain (Felienne Hermans) — comment le cerveau lit du code, et pourquoi la carte mentale bat la lecture exhaustive

The essentials

First day of the internship: repo access, 150,000 lines written by people you don’t know, and a ticket. The natural reflex — read everything to “understand before acting” — is exactly the wrong one. Nobody knows the whole codebase, not even the lead who has been there for five years. Effective developers don’t understand everything: they know how to find things fast, with a rough mental map and precise search techniques.

The skill tested in interviews is therefore not “knowing” but exploring: where you enter, how you follow a thread, who you ask and how, how you ship a first risk-free change. It’s one of the rare questions where the recruiter directly evaluates what you’ll actually do in your first week.

Three principles stand in for a method:

Run it before reading it. An app running locally is a playground for experiments; code read cold is fiction.
Follow one thread, not the whole ball. One request, one feature, one bug — end to end. The map builds up thread by thread.
Code lies less than docs. Stale README, abandoned wiki: the tests and git log are the only sources that are always up to date.

How it works

Day 1: clone, run, take notes. Clone, follow the README to the letter, and write down every missing or wrong step: the undocumented environment variable, the implicit Node version, the service that must run alongside. Those notes are gold (see below). Goal for the day: the app runs locally and you know how to run the tests. Nothing else.

Then: find the entry points. Every codebase has doors: the main(), the routes file, event handlers, cron jobs. From a door, follow one request end to end — the move that yields the most understanding per minute:

HTTP POST /orders
      │
      ▼
routes/orders.ts          ← the entry door
      │
      ▼
OrderController.create()  ← validation, auth
      │
      ▼
OrderService.place()      ← business logic lives here
      │
      ▼
OrderRepository ────────▶ PostgreSQL

One round trip like this teaches you the real architecture (not the wiki’s): the layers, the naming conventions, where business logic lives.

Reflexes by situation:

Situation	Reflex
“Where is X handled?”	`rg` on a visible string (error message, UI label)
“What does this file do?”	Its tests first, then `git log --follow`
“Is this behavior intended?”	If it’s tested, it’s intended
“Who can help me on this module?”	`git shortlog -sn -- path/`
“Where does this request come in?”	Routes file / framework entry point
“My grep finds nothing”	Search the exact error string, not the assumed name

A typical exploration session, starting from an error message:

# Concrete starting point: a string visible in the API
rg "insufficient stock" -l
#   → src/services/order.service.ts

# Who uses this service? (the dependency map)
rg "OrderService" -t ts -l

# The file's history: commits tell you the why
git log --follow --oneline -15 -- src/services/order.service.ts

# Who has the context? (who to ask THE right question)
git shortlog -sn -- src/services/order.service.ts

# The living spec: tests describe the expected behavior
rg "insufficient" src --glob "*.test.ts"

💡 The README you write while onboarding — during your first two weeks, you are the only person on the team seeing the codebase with fresh eyes. Every missing setup step, every implicit convention you write down becomes a docs PR the team could no longer write themselves. Often the best first contribution: useful, risk-free, and it proves you turn your confusion into value.

Key concepts to master

Progressive mapping: the goal is never “understand everything” but to keep a map up to date — the 5-6 main modules, their boundaries, who talks to whom. Details load on demand, when a ticket takes you there.
Tests as documentation: a test describes expected behavior, with executable examples, guaranteed current (otherwise CI is red). Read order.service.test.ts before order.service.ts: nominal and edge cases are listed there.
Git as the team’s memory: git log on a file tells you why it exists; git blame on a strange line leads back to the commit (and often the ticket) that introduced it; the most-modified files are the hot files, the ones concentrating activity — and bugs.
Asking questions intelligently: timebox the search (30-45 min), then ask while showing the path already covered: “I’m looking for where X is validated; I checked the controller and grepped for ‘X’, I see the format validation but not the business rule — where does it live?”. This form proves effort, frames the answer, and nobody finds it annoying.
The first PR: small and safe: a docs typo, a missing setup step, a test on an uncovered edge case. The goal isn’t to shine but to go through the entire pipeline (branch, PR, review, CI, merge, deploy) on a change whose review takes two minutes.
The debugger as an exploration tool: a breakpoint on the handler + the call stack = the real architecture in a single run, where static reading can lie (dependency injection, indirections).

🎤 In an interview — “How would you approach our codebase?” is a real interview question, sometimes asked in front of a real screen. Winning answer: walk through the method (run the app, read the tests of the relevant module, follow one request, git log the hot files) rather than promising to “read everything”. Bonus: ask “do you have onboarding docs? If not, my first PR will start them”.

In an interview

“We drop you into our 200k-line codebase on Monday: what do you do the first week?” — Day 1: clone, get it running, run the tests, note everything missing from the README. Days 2-3: follow one request end to end to understand the real layers, spot the hot files with git log. End of week: one tiny first PR (setup docs, missing test) to cross the full pipeline. I’m not trying to understand everything: I build a map, module by module, pulled by tickets.

“You’re stuck on an incomprehensible piece of code, what do you do?” — Its tests first (the expected behavior), then git blame → the commit → the ticket (the why). If that’s not enough: timebox, then a question to the author (found via blame/shortlog) showing what I already explored. Staying stuck for two hours in silence costs the team more than asking after 30 minutes with context.

“What makes a good first PR?” — Small, safe, useful: fixing the setup README, a test on an edge case, a typo. It validates that I can run the team’s whole workflow (branch, commit conventions, review, CI) on a zero-risk change. The big feature comes when the map is reliable.

“What do tests give you in code you’re discovering?” — Executable documentation: they list expected behaviors and edge cases, and they’re current by construction. They also act as a harness: before modifying code I don’t fully master, a test capturing current behavior protects me from regressions.

“The README says X but the code does Y: who do you believe?” — The code, always: it’s what runs in production, the README ages. But the gap is information in itself: I check with git log whether Y is recent, ask whether the change is intended, and fixing the README becomes a PR.

Pitfalls & misconceptions

⚠️ Early refactoring — the code that looks “bad” to you in week one often has a reason you can’t see yet: business constraint, historical bug, external dependency. That’s Chesterton’s fence: you only remove a fence after understanding why it’s there. Proposing a big refactoring in week 1 is the junior signal par excellence.

“I must understand everything before touching anything” — no: understanding comes from doing. One well-chosen ticket teaches more than three days of passive reading.
Staying stuck in silence to “avoid bothering people”: beyond 30-45 minutes of genuine searching, not asking costs the team more than asking.
The opposite too: asking before searching burns your credit. The question must show the path already covered.
Trusting docs over code: wikis and READMEs drift; tests and git log don’t lie.
The ambitious first PR: 800 lines in week 1 = endless review, maximum risk, wrong signal. Small, safe, merged.

Going further

Understand Legacy Code — Nicolas Carlo’s blog, entirely dedicated to the topic
Working Effectively with Legacy Code (Michael Feathers) — the classic: test harnesses, seams, safe changes
ripgrep — learn rg inside out, the number one exploration tool
git log and git blame — the options that change everything: --follow, -S (pickaxe), -L
The Programmer’s Brain (Felienne Hermans) — how the brain reads code, and why the mental map beats exhaustive reading

S'entraîner sur ce sujet → Practice this topic →