Leçons de Clean Code de Robert C. Martin pour accélérer les équipes

Pourquoi Clean Code compte encore pour les équipes modernes

Robert C. Martin — plus connu sous le nom d'« Uncle Bob » — a popularisé le mouvement Clean Code avec une idée simple : le code doit être écrit pour la prochaine personne qui devra le modifier (souvent, cette personne, c'est vous dans trois semaines).

Maintenabilité et vélocité d'équipe (en clair)

Maintenabilité : la facilité pour votre équipe de comprendre le code, le modifier en toute sécurité et livrer ces modifications sans casser des parties non liées. Si chaque petite modification semble risquée, la maintenabilité est faible.

Vélocité d'équipe : la capacité régulière de l'équipe à livrer des améliorations utiles dans le temps. Ce n'est pas « taper plus vite » — c'est la rapidité pour passer d'une idée à un logiciel fonctionnel, de manière répétée, sans accumuler des dommages qui vous freinent ensuite.

Pourquoi la qualité du code est une affaire d'équipe

Clean Code n'est pas une affaire de goûts personnels d'un développeur. C'est un environnement de travail partagé. Un module en désordre ne frustre pas seulement son auteur ; il augmente le temps de revue, complique l'onboarding, crée des bugs plus longs à diagnostiquer et force tout le monde à avancer prudemment.

Quand plusieurs personnes contribuent au même code, la clarté devient un outil de coordination. L'objectif n'est pas le « code élégant », mais le changement prévisible : n'importe qui dans l'équipe peut faire une mise à jour, comprendre ce que cela affecte, et merger en confiance.

Des habitudes pratiques, pas la perfection

Clean Code peut être poussé à l'extrême si on le traite comme un test de pureté. Les équipes modernes ont besoin de directives qui rapportent sous des délais réels. Pensez-y comme un ensemble d'habitudes qui réduisent les frictions — de petits choix qui s'additionnent pour accélérer la livraison.

Dans la suite de cet article, nous nous concentrerons sur trois domaines qui améliorent directement la maintenabilité et la vélocité :

• Nommage : rendre le sens évident pour que l'on passe moins de temps à décoder l'intention.
• Frontières : séparer les responsabilités pour que les changements n'entraînent pas d'effets de bord.
• Discipline : pratiques constantes (revues, tests, refactoring) qui empêchent la base de code de retomber dans le chaos.

L'idée centrale de Clean Code : optimiser pour le changement

Clean Code n'est pas d'abord une question d'esthétique ou de préférence personnelle. Son but pratique : rendre le code facile à lire, simple à raisonner et donc facile à changer.

Les équipes ont rarement du mal parce qu'elles ne savent pas écrire du code nouveau. Elles peinent parce que le code existant est difficile à modifier en toute sécurité. Les exigences bougent, les cas limites apparaissent, et les deadlines ne s'arrêtent pas pendant qu'on « réapprend » le système.

Clair bat clever

Le code « clever » optimise souvent la satisfaction momentanée de l'auteur : logique dense, raccourcis inattendus ou abstractions astucieuses qui paraissent élégantes — jusqu'au moment où quelqu'un d'autre doit les modifier.

Le code « clair » optimise pour le prochain changement. Il favorise un flux de contrôle simple, une intention explicite et des noms qui expliquent pourquoi quelque chose existe. L'objectif n'est pas de supprimer toute complexité (ce n'est pas possible), mais de placer la complexité là où elle doit être et de la garder visible.

Le coût de la confusion est mesurable

Quand le code est difficile à comprendre, l'équipe le paie plusieurs fois :

• Livraison plus lente : plus de temps passé à lire, tracer et vérifier.
• Plus de bugs : des incompréhensions mènent à des corrections incorrectes ou partielles.
• Plus de retouches : les ingénieurs mettent en place des contournements parce que « toucher cette zone fait peur », ce qui ajoute de la dette technique.

C'est pourquoi Clean Code est directement lié à la vélocité : réduire la confusion réduit l'hésitation.

Des principes, pas des commandements

Clean Code est un ensemble d'arbitrages, pas de règles rigides. Parfois, une fonction un peu plus longue est plus claire que la fractionner. Parfois, une contrainte de performance justifie une approche moins « jolie ». Le principe reste le même : préférez les choix qui gardent les changements futurs sûrs, locaux et compréhensibles — parce que le changement est l'état par défaut du logiciel réel.

Nommage : le chemin le plus rapide vers un code lisible et maintenable

Si vous voulez du code facile à modifier, commencez par les noms. Un bon nom réduit la quantité de « traduction mentale » qu'un lecteur doit faire — il peut ainsi se concentrer sur le comportement, pas sur le sens des choses.

Ce qu'un bon nom doit communiquer

Un nom utile porte de l'information :

• Intention : ce que représente l'entité ou ce qu'elle fait (pas comment elle est implémentée).
• Portée : est-ce une valeur unique, une collection, un cache, une requête, un brouillon ?
• Unités et format : Cents vs Dollars, Utc vs heure locale, Bytes vs Kb, chaîne vs objet parsé.
• Contraintes : inclut-elle la taxe, est-elle réduite, est-elle validée, est-ce un maximum ?

Quand ces détails manquent, le lecteur doit poser des questions — ou pire, deviner.

Noms ambigus vs noms clairs (exemples)

Les noms vagues cachent des décisions :

• data, info, tmp, value, result
• list, items, map (sans contexte)

Les noms clairs donnent du contexte et réduisent les suivis :

• invoiceTotalCents (unité + domaine)
• discountPercent (format + sens)
• validatedEmailAddress (contrainte)
• customerIdsToDeactivate (portée + intention)
• expiresAtUtc (fuseau horaire)

Même de petits renommages peuvent prévenir des bugs : timeout est flou ; timeoutMs ne l'est pas.

Cohérence : coller au langage produit

Les équipes vont plus vite quand le code utilise les mêmes mots que les tickets, le texte UI et le support client. Si le produit dit « abonnement », évitez d'appeler cela plan dans un module et membership dans un autre sauf si ce sont de vrais concepts différents.

La cohérence, c'est aussi choisir un terme et s'y tenir : customer vs client, invoice vs bill, cancel vs deactivate. Si les mots dérivent, le sens dérive aussi.

Le nommage est une coordination, pas un style

Les bons noms agissent comme de petits bouts de documentation. Ils réduisent les questions Slack (« Que contient tmp déjà ? »), diminuent les allers-retours en revue et évitent les incompréhensions entre ingénieurs, QA et produit.

Checklist rapide pour les noms

Avant de committer un nom, demandez-vous :

• Un nouveau collègue devinerait-il ce que c'est sans ouvrir d'autres fichiers ?
• Indique-t-il les unités / fuseau horaire / format quand c'est important ?
• Est-il aligné avec la terminologie produit ?
• Évite-t-il des mots « conteneurs » comme data sauf si le domaine est explicite ?
• Si c'est un booléen, se lit-il clairement : isActive, hasAccess, shouldRetry ?

Garder les noms honnêtes : éviter la dérive des noms dans le temps

Un bon nom est une promesse : il dit au prochain lecteur ce que fait le code. Le problème, c'est que le code change plus vite que les noms. Au fil des mois, avec des modifications rapides et du « ship it », une fonction validateUser() commence à faire validation et provisionnement et analytics. Le nom semble toujours propre, mais il est trompeur — et les noms trompeurs coûtent du temps.

Pourquoi les noms doivent refléter ce que le code fait aujourd'hui

Clean Code n'est pas de trouver le nom parfait une fois pour toutes. C'est garder les noms alignés avec la réalité. Si un nom décrit ce que le code faisait, chaque futur lecteur doit rétro-engineerer la vérité depuis l'implémentation. Cela augmente la charge cognitive, ralentit les revues et rend les petites modifications plus risquées.

Comment la dérive arrive dans les équipes réelles

La dérive arrive rarement intentionnellement. Elle vient souvent de :

• Correctifs rapides : patcher un comportement sous pression sans revoir l'intention.
• Creep fonctionnel : ajouter « encore une responsabilité » à une fonction existante parce que c'est pratique.
• Copier-coller : cloner du code et modifier la logique sans changer les noms.

Moyens légers pour garder les noms fidèles

Pas besoin d'un comité de nommage. Quelques habitudes simples suffisent :

• Quand une fonction gagne une responsabilité, soit renommez-la, soit scindez-la pour que l'ancien nom reste vrai.
• Ajoutez en revue la case : « Les noms décrivent-ils toujours le comportement ? » (C'est rapide et ça détecte beaucoup de cas.)
• Si vous écrivez un commentaire du type « En fait… », c'est souvent un signal pour renommer.

Règle « renommer quand on touche »

Lors de toute petite modification — correction, refactor ou ajustement de fonctionnalité — prenez 30 secondes pour ajuster le nom trompeur le plus proche. Cette habitude empêche l'accumulation de dérive et améliore la lisibilité avec le travail quotidien.

Frontières : séparer les responsabilités pour réduire les effets de bord

Clean Code ne se limite pas à des méthodes propres — il s'agit de tracer des frontières claires pour que le changement reste local. Les frontières apparaissent partout : modules, couches, services, API, et même dans « qui est responsable de quoi » à l'intérieur d'une classe.

Séparation des préoccupations (analogie de cuisine)

Imaginez une cuisine avec des postes : préparation, grill, dressage, plonge. Chaque poste a un travail clair, des outils et des entrées/sorties. Si le poste grill commence à laver la plonge « juste cette fois », tout ralentit : les outils disparaissent, des files se forment et on ne sait plus qui est responsable quand quelque chose casse.

Le logiciel fonctionne de la même manière. Quand les frontières sont claires, vous pouvez modifier le « poste grill » (logique métier) sans réorganiser la « plonge » (accès aux données) ou le « dressage » (formatage UI/API).

Comment les frontières floues ralentissent l'équipe

Les frontières floues créent des effets de bord : une petite modification oblige à retoucher plusieurs zones, tests additionnels, plus d'allers-retours en revue et plus de risque de bugs inattendus. L'équipe commence à hésiter — chaque changement paraît susceptible de casser autre chose.

Signes courants :

• Responsabilités mélangées : un module calcule les prix et écrit en base.
• Raccourcis cross-couches : le code UI interroge la base « pour la perf ».
• Abstractions qui fuient : un service expose des tables internes ou des objets ORM comme API publique.
• Utilitaires « helper » qui amassent des comportements non liés.

Ce que donnent de bonnes frontières au quotidien

Avec de bonnes frontières, les tickets deviennent prévisibles. Un changement de règle de tarification touche principalement le composant de tarification, et les tests indiquent rapidement si vous avez franchi une limite. Les revues sont plus simples (« cela appartient à la couche domaine, pas au controller »), et le débogage est plus rapide car chaque pièce a un endroit et une raison de changer.

Fonctions courtes et intention claire : rendre le changement plus sûr

Les fonctions petites et focalisées facilitent le changement car elles réduisent le contexte à garder en tête. Quand une fonction a un seul travail clair, vous pouvez la tester avec quelques entrées, la réutiliser ailleurs et comprendre les erreurs sans traverser un labyrinthe d'étapes non liées.

« Faire une seule chose » (exemple concret)

Considérez une fonction processOrder() qui : valide une adresse, calcule la taxe, applique des réductions, prélève une carte, envoie un e-mail et écrit des logs d'audit. Ce n'est pas « traiter une commande » — c'est cinq décisions et trois effets de bord empaquetés.

Une approche plus propre sépare les intentions :

function processOrder(order) {
  validate(order)
  const priced = price(order)
  const receipt = charge(priced)
  sendConfirmation(receipt)
  return receipt
}

Chaque helper peut être testé et réutilisé indépendamment, et la fonction de haut niveau se lit comme une courte histoire.

Pourquoi les fonctions longues sont risquées

Les fonctions longues cachent des points de décision et des cas limites parce qu'elles enterrent la logique « et si ? » au milieu d'autres tâches. Un seul if pour « adresse internationale » peut affecter la taxe, l'expédition et le libellé de l'email — mais la connexion est difficile à percevoir à 80 lignes de distance.

Étapes pratiques de refactor

Commencez petit :

• Extraire une fonction : isolez un bloc cohérent en calculateTax() ou formatEmail().
• Renommer : mettez à jour les noms pour décrire des résultats (applyDiscounts vs doDiscountStuff).
• Supprimer les duplications : si deux branches répètent les mêmes étapes, extrayez un helper partagé.

Garde-fous (éviter la sur-fragmentation)

Petit ne veut pas dire « minuscule à tout prix ». Si vous créez beaucoup de wrappers d'une ligne qui forcent le lecteur à sauter entre cinq fichiers pour comprendre une action, vous avez échangé clarté contre indirection. Visez des fonctions courtes, significatives et compréhensibles localement.

Gérer les effets de bord : moins de surprises, débogage plus facile

Un effet de bord est tout changement qu'une fonction fait au-delà de retourner une valeur. En clair : vous appelez un helper en attendant une réponse, et il change discrètement autre chose — écrit un fichier, met à jour une ligne en base, muta un objet partagé, ou bascule un flag global.

Les effets de bord ne sont pas automatiquement « mauvais ». Le problème, ce sont les effets de bord cachés. Ils surprennent les appelants, et les surprises transforment des changements simples en longues sessions de débogage.

Pourquoi les effets de bord ralentissent l'équipe

Les changements cachés rendent le comportement imprévisible. Un bug peut apparaître dans une partie de l'appli mais être causé par un helper « pratique » ailleurs. Cette incertitude tue la vélocité : les ingénieurs passent du temps à reproduire, ajouter des logs temporaires et débattre de qui devrait être responsable.

Ils rendent aussi le code plus difficile à tester. Une fonction qui écrit en base ou touche un état global nécessite un setup/teardown, et les tests commencent à échouer pour des raisons sans rapport avec la fonctionnalité en cours.

Patterns qui réduisent les surprises

Privilégiez des fonctions avec des entrées et sorties claires. Si quelque chose doit modifier le monde, rendez-le explicite :

• Injectez les dépendances (logger, repository, clock) au lieu d'aller chercher des globaux.
• Séparez « calculer » et « faire » : une fonction calcule ; une autre effectue l'écriture.
• Nommez les effets honnêtement (ex. saveUser() vs getUser()).

Pièges fréquents : logging dans des helpers bas niveau, mutation d'objets de configuration partagée, écritures en base lors d'étapes de formatage ou de validation.

Checklist rapide de revue

En revue, posez une question simple : « Qu'est-ce qui change à part la valeur retournée ? »

Suivantes : mute-t-il les arguments ? Touche-t-il l'état global ? Écrit-il sur disque/réseau ? Déclenche-t-il des jobs d'arrière-plan ? Si oui, peut-on rendre cet effet explicite — ou le déplacer vers une meilleure frontière ?

Discipline : l'effet composé sur la vitesse de livraison

Clean Code n'est pas qu'une préférence de style — c'est de la discipline : des habitudes répétables qui gardent la base de code prévisible. Pensez-y moins comme « écrire du joli code » et plus comme des routines qui réduisent la variance : tests avant les changements risqués, petits refactors quand vous touchez du code, documentation légère où elle évite la confusion, et revues qui détectent les problèmes tôt.

Vitesse maintenant vs vitesse sur le mois suivant

Les équipes peuvent souvent « aller vite » aujourd'hui en sautant ces habitudes. Mais cette vitesse est généralement empruntée au futur. La facture arrive sous forme de releases instables, régressions surprises et agitation tardive quand une modification simple déclenche une réaction en chaîne.

La discipline échange un petit coût constant contre de la fiabilité : moins d'urgences, moins de corrections de dernière minute et moins de situations où l'équipe doit tout arrêter pour stabiliser une release. Sur un mois, cette fiabilité devient un débit réel.

Pratiques quotidiennes qui se cumulent

Quelques comportements simples rapportent vite :

• Ajouter ou mettre à jour un test quand on corrige un bug (pour qu'il reste corrigé).
• Refactorer « la zone que vous avez touchée » pendant que c'est encore en mémoire (renommer, extraire une fonction, retirer des duplications).
• Garder des changements petits et faciles à revoir (branches de courte durée, descriptions de PR claires).
• Traiter la revue comme une responsabilité partagée : demander « la prochaine personne comprendra-t-elle ceci ? » plutôt que « est-ce que ça marche ? »

« On n'a pas le temps pour la propreté »

Cet argument est souvent vrai sur le moment — et coûteux dans la durée. Le compromis pragmatique, c'est la portée : ne programmez pas un grand nettoyage ; appliquez la discipline aux bords du travail quotidien. En quelques semaines, ces petits dépôts réduisent la dette technique et augmentent la vitesse de livraison sans réécriture massive.

Les tests comme gardiens de frontières et filet de sécurité pour le refactoring

Les tests ne servent pas seulement à « attraper des bugs ». En termes Clean Code, ils protègent les frontières : le comportement public que votre code promet aux autres parties du système. Quand vous changez l'intérieur — scinder un module, renommer des méthodes, déplacer la logique — de bons tests confirment que vous n'avez pas cassé le contrat.

Un feedback rapide vaut mieux que des corrections tardives

Un test qui échoue quelques secondes après un changement est bon marché à diagnostiquer : vous vous souvenez encore de ce que vous avez touché. Comparez cela à un bug trouvé des jours plus tard en QA ou en production, quand la piste est froide, la correction est plus risquée et plusieurs changements sont emmêlés. Le feedback rapide transforme le refactor en routine.

Que tester en premier (quand le temps est limité)

Commencez par une couverture qui vous donne de la liberté :

• Comportement critique : flux qui rapportent de l'argent, protègent des données ou bloquent des utilisateurs.
• Logique délicate : cas limites, parsing, fuseaux horaires, arrondis, permissions.
• Échecs courants : entrées connues comme problématiques, intégrations instables, règles de retry.

Heuristique pratique : si un bug serait coûteux ou embarrassant, écrivez un test qui l'aurait détecté.

Garder les tests lisibles — comme de la documentation

Des tests propres accélèrent le changement. Traitez-les comme des exemples exécutables :

• Nommez les tests selon l'intention : rejects_expired_token() se lit comme une exigence.
• Préférez un setup clair plutôt que des helpers opaques. Si un helper cache du sens, il ne sert pas.
• Affirmez les résultats, pas les étapes internes. Vous voulez la liberté de réécrire l'implémentation.

Éviter les tests fragiles qui ralentissent le changement

Les tests deviennent une charge quand ils vous enferment dans la structure actuelle — trop de mocks, assertions sur des détails privés, ou dépendance sur du texte UI exact quand vous ne vous souciez que du comportement. Les tests fragiles tombent pour du « bruit », et l'équipe finit par ignorer les builds rouges. Visez des tests qui échouent seulement quand quelque chose d'important casse.

Habitudes de refactor : petits pas qui gardent la dette sous contrôle

Le refactoring est l'une des leçons Clean Code les plus pratiques : c'est une amélioration préservant le comportement de la structure du code. Vous ne changez pas ce que le logiciel fait ; vous changez la façon dont il sera plus facile à modifier la prochaine fois. Adoptez la règle du Boy Scout : laissez le code un peu plus propre que vous l'avez trouvé.

Refactors sûrs et petits qui rapportent vite

Les meilleurs refactors sont à faible risque et faciles à relire. Quelques-uns réduisent régulièrement la dette :

• Renommer variables, fonctions et classes pour correspondre à ce qu'elles font vraiment (surtout après évolution des exigences).
• Extraire une méthode quand un bloc a un but unique mais est enfoui dans une longue fonction.
• Simplifier des conditionnels en supprimant des négations, en regroupant des branches dupliquées ou en introduisant des helpers bien nommés.

Ces changements sont petits, mais rendent l'intention évidente — ce qui raccourcit le débogage et accélère les modifications futures.

Quand refactorer (sans bloquer la livraison)

Le refactor marche mieux quand il est lié à un travail réel :

• Avant d'ajouter une feature : dégagez la voie pour que le nouveau code s'insère naturellement, plutôt que d'imposer des contournements.
• Après avoir corrigé un bug : une fois que vous avez trouvé le point faible, rendez difficile le retour du même type de bug.

Quand s'arrêter

Le refactor n'est pas une licence pour un nettoyage sans fin. Arrêtez-vous quand l'effort devient une réécriture sans objectif testable clair. Si le changement ne peut pas être exprimé comme une série d'étapes petites et revues séparément (chacune sûre à merger), découpez-le en jalons — ou ne le faites pas encore.

Revues de code et standards : transformer des principes en habitudes d'équipe

Clean Code n'améliore la vélocité que lorsqu'il devient un réflexe d'équipe — pas une préférence individuelle. Les revues de code sont le lieu où des principes comme le nommage, les frontières et les petites fonctions deviennent des attentes partagées.

À quoi sert une revue

Une bonne revue optimise pour :

• Compréhension partagée : plus que « LGTM » — l'équipe doit savoir ce qui a changé et pourquoi.
• Cohérence : noms, structure et conventions qui rendent le code familier dans la base.
• Vérification des frontières : les responsabilités sont-elles séparées ?
• Gestion du risque : identifier les effets de bord, cas limites et questions de déploiement tôt.

Template de revue léger

Utilisez une checklist répétable pour accélérer les approbations et réduire les allers-retours :

1. Intention : Quel problème résout ce changement ? Le design est-il simple ?
2. Lisibilité : Les noms sont-ils spécifiques et honnêtes ? Y a-t-il du code « clever » qui pourrait être plus clair ?
3. Frontières : Avons-nous gardé les responsabilités au bon endroit (UI/service/domaine/données) ?
4. Tests : Qu'est-ce qui prouve que ça marche ? Qu'est-ce qui échouerait si ça casse plus tard ?
5. Risques : Performance, sécurité, migrations, compatibilité.
6. Suivis : Quelle dette avons-nous intentionnellement différée (ticket/lien) ?

Standards qui réduisent les débats

Des standards écrits (conventions de nommage, structure de dossiers, patterns de gestion d'erreurs) rabattent les discussions subjectives. Au lieu de « Je préfère… », le relecteur peut pointer « On fait ainsi », ce qui rend les revues plus rapides et moins personnelles.

Bienveillance et clarté

Critiquez le code, pas le codeur. Préférez questions et observations plutôt que jugements :

• « Pourrait-on renommer process() en calculateInvoiceTotals() pour refléter ce qu'il retourne ? »
• « Cette fonction traverse la frontière de persistance — le repository devrait-il contenir cette requête ? »

Commentaires : utiles vs bruit

Bon commentaire :

// Why: rounding must match the payment provider’s rules (see PAY-142).

Commentaire inutile :

// increment i

Visez des commentaires qui expliquent pourquoi, pas ce que le code dit déjà.

Comment appliquer Clean Code pour améliorer la vélocité (sans dogmatisme)

Clean Code n'aide que si cela facilite le changement. La façon pragmatique de l'adopter : traitez-le comme une expérience — mettez-vous d'accord sur quelques comportements, suivez les résultats et conservez ce qui réduit mesurablement les frictions.

Ceci est d'autant plus important à l'ère des outils d'assistance IA. Que vous génériez des squelettes avec un LLM ou que vous itériez dans un flux type Koder.ai, les mêmes principes s'appliquent : noms clairs, frontières explicites et refactoring discipliné permettent d'éviter que l'itération rapide ne devienne un spaghettis difficile à faire évoluer. Les outils accélèrent la production ; les habitudes Clean Code préservent le contrôle.

Mesurer la vélocité en mesurant la friction

Au lieu de débattre du style, regardez des signaux qui corrèlent avec les ralentissements :

• Temps de cycle PR : temps entre ouverture et merge (et temps passé « en attente de revue »).
• Taux de défauts : bugs trouvés en QA/production par release.
• Temps d'onboarding : combien de temps avant qu'un nouveau puisse livrer une modification sûre.
• Retouches : pourcentage de travail repris (rollback, tickets rouverts, « fix the fix »).

Tenir un « journal de friction » léger

Une fois par semaine, passez 10 minutes à noter les problèmes récurrents dans une note partagée :

• « Difficile de trouver où X est implémenté. »
• « Les tests cassent pour des changements non liés. »
• « Ce module a trop de raisons de changer. »

Avec le temps, des motifs émergent. Ils indiquent quelle habitude Clean Code rapportera le plus.

Créer un petit accord d'équipe

Gardez-le simple et applicable :

• Règles de nommage : privilégier des noms révélant l'intention ; bannir les mots vagues comme data, manager, process sauf si le domaine l'explique.
• Règles de frontières : un module = une responsabilité claire ; éviter de mélanger persistance, règles métier et formatage.
• Minimum de tests : chaque correction de bug ajoute un test ; un nouveau comportement est livré avec un test au niveau approprié.

Plan de déploiement sur 30 jours (une habitude par semaine)

• Semaine 1 — Nommage : renommez les pires éléments que vous touchez ; exigez « le nom correspond-il encore ? » dans les PRs.
• Semaine 2 — Frontières : extrayez une seam de dépendance (ex. envelopper une API externe derrière une interface).
• Semaine 3 — Effets de bord : rendez un flux plus prévisible (retours de valeurs plutôt que mutations cachées ; logging en périphérie).
• Semaine 4 — Refactor avec tests : choisissez un fichier chaud et améliorez-le en petites PRs.

Mesurez les métriques en fin de semaine et décidez quoi garder.

Checklist rapide

• Un nouveau venu trouve-t-il l'endroit du changement en moins de 2 minutes ?
• Les noms correspondent-ils encore au comportement après le dernier edit ?
• Existe-t-il une frontière claire entre la logique métier et l'I/O ?
• Peut-on changer une partie sans toucher cinq autres ?
• Cette PR réduit-elle le travail futur (ou l'augmente-t-elle) ?