Tout commence lorsque notre PO, vient nous voir pour nous montrer un problème avec la liste des offres mises en favoris. Pour une catégorie d’offre en particulier, l’icône favori n’est pas dans le bon état.

Première action, j’essaie de reproduire le problème. Avant de foncer dans le code, je cherche les scénarios utilisateurs qui provoquent le problème et je les note. Et ensuite, avec ça, je peux me prouver que l’anomalie est résolue en ayant écrit des tests et en rejouant le scénario avec/sans correctif. C’est un des premiers conseils que je voudrais partager dans cette histoire.

Grâce à un scénario précis, on peut également affiner l’origine du problème. Par exemple, ici, ça m’a permis de voir que le problème n’était absolument pas lié à la catégorie de l’offre. L’origine se situait dans notre cache HTTP - il nous manquait une invalidation du cache suite à une action spécifique. On corrige le problème en pair-programming et, tout content de notre avancée, on informe notre PO qu’une nouvelle version de l’application est déployée en recette. On passe à autre chose. Fin de l’histoire, tous les problèmes sont résolus.

Tous ? Non ! Un village peuplé d’irréductibles anomalies résiste encore et toujours aux développeurs. Le fil à retordre va devenir bien rigide.

À notre grande surprise, notre PO revient me voir : “je fais comme avant et j’ai le même problème, la correction n’aide pas”. Ok. Très étrange. On a pourtant bien constaté la résolution avec nos scénarios. La cause identifiée était parfaitement logique. La partie métier est très bien couverte par des tests. Je recommence le scénario sur mon téléphone, c’est OK. Qu’est-ce qui diffère entre nos téléphones ?

Frédéric a constamment le problème alors que de mon côté, je ne l’ai jamais. En creusant et en essayant diverses choses (même modèle de téléphone, s’échanger les comptes utilisateurs, …), on finit par trouver. Il télécharge l’application depuis Firebase Distribution alors que moi je l’exécute directement depuis mon IDE. On a la même base de code, mais la compilation diffère légèrement - lorsqu’une application est déployée, elle est compilée en mode release (il y a des optimisations, des règles plus strictes, etc).

Super ! On sait reproduire à 100%. Super ! Compiler en mode release signifie aussi que je me coupe de tout un tas d’outils de développeurs pour observer ce qu’il se passe. Je ne peux pas debugger avec des breakpoints, je ne peux pas lire les logs, je ne peux pas observer les échanges réseaux, et, très embêtant, les build en mode release sont bien plus long à générer que l’exécution en mode debug.

À ce moment-là, je me dis qu’on a un bon problème mystique. Je n’arrive pas à reproduire à 100% en mode debug, et on ne sait rien de la cause. C’est à mon tour de changer de mode : je passe en mode “enquête”.

Je commence par ouvrir un document pour écrire ce que je sais du contexte et du scénario qui reproduit le problème. Ça me permet de rassembler toutes les informations, de vérifier si je passe à côté de quelque chose d’évident en l’explicitant, et de pouvoir mieux communiquer. Puis je lance une multitude d’hypothèses. On a plusieurs appels HTTPs qui se déclenchent au lancement de l’application, dont la liste des favoris. Est-ce que notre backend rejette certaines requêtes parce qu’un même compte utilisateur fait trop d’appels simultanés ? Est-ce le client HTTP utilisé dans l’application ? Est-ce le cache HTTP ? Est-ce l’OS du téléphone qui empêche de faire trop de requêtes dans un trop court laps de temps ? Etc. J’essaie de ne fermer aucune porte.

Ensuite, je me lance dans des expérimentations rapides. Je cherche à valider ou invalider des hypothèses pour affiner progressivement l’origine. Pour le moment l’éventail des possibilités est trop larges. Je cherche aussi à apprendre de nouvelles informations avec les résultats de ces expérimentations.

Je commence par m’orienter sur le backend. Je veux voir ce qu’il se passe alors j’ouvre Elastic (un outils d’analyse de logs très puissant ajouté sur notre backend) et je filtre les logs sur l’identifiant de mon compte utilisateur. Tiens, la requête des favoris n’apparaît pas. Je vais voir un développeur backend pour creuser cette curiosité. On fait plusieurs vérifications, notre backend n’a pas de mécanisme pour rejeter la requête, et ce n’est pas l’infrastructure non plus. J’invalide donc l’hypothèse du backend, et je repars avec un apprentissage intéressant : la requête n’arrive pas au backend.

Je repasse sur l’application mobile. Je veux travailler l’hypothèse du cache. Au tout début, j’ai effectué un correctif mais il reste un problème. Le mécanisme dans sa globalité a un peu de complexité, je cherche un réponse stricte et binaire : est-ce que ça vient du cache, OUI ou NON ? Je désactive le cache simplement, au plus haut niveau, sur toutes les routes - il n’est plus du tout utilisé. Résultat, le problème est toujours là, l’hypothèse est invalidée.

Il faut chercher ailleurs, mais je manque d’indices. J’ai besoin de rendre l’application davantage observable. Pour rappel, en mode release, l’application n’écrit pas dans la console lorsque l’on appelle la fonction notre logger. Néanmoins, la fonction est tout de même appelée. Eh bien, je peux modifier la fonction pour stocker les logs en mémoire, et ajouter un bouton sur la page d’accueil qui me permet de me partager les logs (via un mail ou une note synchronisée dans le cloud). Je peux faire ça très rapidement, en quelques minutes.

J’insiste à nouveau sur rapide. Tout le long de mon enquête, je veux une boucle de feedback très courte, je ne cherche pas à coder pendant 3h un truc over engineered ou trop clean ou trop future-proof, ce n’est pas le but. Je ne conserverais aucun code à la fin. Lorsque j’aurais quelque chose qui fonctionne et qui aura corrigé le problème, je recommencerais proprement de zéro en sachant où je dois aller.

Maintenant que j’ai accès à des logs provenant de l’application, je constate que la requête HTTP ne part pas. Ça confirme ce qu’on a pu voir sur le backend, et le besoin d’avoir plus d’informations pour comprendre pourquoi la requête ne part pas. J’ajoute alors davantage de logs, pour voir si chaque brique est bien appelée. Middleware, repository, action, etc. Tout le cheminement est bien fait, et ce n’est pas surprenant vu que le use case est couvert par des tests.

Il y a quelque chose de plus fin à trouver. Je mets des logs juste avant et juste après l’appel HTTP. Bingo. Une bizzarerie se met en évidence : le log après l’appel HTTP n’est jamais appelé, et il n’y a pas non plus d’exception soulevée. La fonction semble ne jamais rendre la main. Première hypothèse, on pense que c’est dû à la co-existance de deux clients HTTPs (le temps d’une migration douce). Alors on migre vulgairement ces quelques requêtes sur le même client. Invalidée. On commente les appels réseaux au démarrage, sauf ceux des favoris. Invalidée.

Je saute dans le temps pour arriver à la fin. On fini par identifier la source du problème et y apporter une correction. On comprend au passage qu’il y avait deux problèmes distincts, le premier correctif était aussi nécessaire. Tout fonctionne parfaitement. Victoire, par toutatis !

Au travers de cette histoire, j’ai essayé de mettre en lumière certains aspects. L’utilité d’avoir des scénarios de reproduction précis, tout d’abord, pour vérifier que l’anomalie est corrigée, écrire des tests, éliminer/affiner de premières hypothèses. Puis le fonctionnement en expérimentations rapides. On essaie d’avoir un tas d’hypothèses, d’en sélectionner une à la fois, de valider ou invalider rapidement avec des actions simples, d’apprendre de nouvelles informations pour la suite de l’enquête.

Il y a aussi une notion d’observabilité. On a besoin de comprendre ce qu’il se passe pendant qu’un logiciel est utilisé. Côté backend, on est très bien équipé avec la suite ELK par exemple. Mais côté mobile, Crashlytics n’est pas du tout suffisant. Les crashs ne sont qu’un sous-ensemble des problèmes qui peuvent arriver, et l’interface est loin d’être aussi puissante qu’ElasticSearch. On peut s’améliorer dans ce domaine tout en respectant les contraintes liées à l’écosystème mobile.

À de multiples reprises, j’étais également en pair-programming, avec plusieurs collègues. Rien ne vaux plusieurs cerveaux, plusieurs idées, visions, façons de faire.

La méthode Mikado, c’est un peu la même chose. On suit un plan décomposé en plusieurs petits pré-requis pour atteindre un objectif plus grand bien précis. Sauf que ce plan, on ne l’a pas au départ mais on le construit au fil de notre avancée. Et c’est là toute la puissance de la méthode Mikado. On avance par petits pas, on expérimente, on visualise notre chemin, et on reste toujours dans un état fonctionnel jusqu’à atteindre l’objectif défini.

Je m’en sers régulièrement lors de refactoring et je trouve ça génial (n’en déplaise aux adeptes des chantiers abandonnés après 4 mois sans visibilité). La méthode m’apporte de la structure, je vois ce que j’ai à faire, j’avance par petites étapes. Rencontrer des difficultés ou des imprévus en chemin est moins problématique grâce à l’approche très itérative et expérimentale de la méthode. Je découpe les problèmes, j’essaie des solutions, je garde ce qui marche, j’annule ce qui ne fonctionne pas. Le projet est toujours dans un état fonctionnel. Je peux m’arrêter à tout moment et le livrer.

C’est très puissant pour effectuer des changements progressivement et avec rigueur dans n’importe quel domaine. Je parlais de refactoring, mais on peut effectuer tout type d’évolutions dans notre code, ou également sortir de la sphère technique en l’utilisant dans notre équipe pour modifier une organisation, ou dans notre quotidien.

La méthode Mikado

Avant de plonger profondément dans les détails, je vous propose de découvrir un exemple d’utilisation de la méthode Mikado qui parle à tout le monde pour représenter son fonctionnement.

Les grands principes

Ok. Maintenant que vous avez un exemple simple et concret d’utilisation de la méthode Mikado, nous pouvons décortiquer les grands principes au travers de cette histoire.

Avoir un objectif

On commence avec un objectif précis. Dès le départ, on sait où l’on doit aller, on a un cap. On se concentre dessus, on ne fait pas autre chose en même temps. Dans le récit précédent, le besoin était de remplacer un vieil écran par une nouvelle TV afin de regarder Kaamelott en 4K. Le résultat attendu est parfaitement clair.

Faire des expérimentations

Tout au long de notre chemin pour arriver à notre objectif, on va expérimenter. On va essayer des choses qui nous rapprochent de l’objectif. On avance par petites étapes. On cherche des solutions simples et naïves. Par exemple, on essaie de brancher directement la nouvelle TV et on voit ce qu’il se passe.

N’essayez pas de tout prévoir en avance, de faire un plan complet pour aller sur la lune. Demandez-vous ce que vous pouvez faire comme toute première étape pour avancer. Mettre le Blu-ray ? Ok, j’essaie.

Valider une expérimentation réussie

Lorsqu’une expérimentation fonctionne, on la valide. On commit, on enregistre, on garde ces modifications. Elles nous permettent d’avancer. Et si on arrête là, tout fonctionne toujours. On n’a peut-être pas terminé, mais on a avancé dans le schmilbik. J’ai acheté le Blu-ray de Kaamelott, je me suis rapproché de mon objectif final.

Annuler une expérimentation échouée

Quand une expérimentation rate, on annule. On retire toutes les modifications de notre expérimentation et on revient dans l’état précédant. On restore sur git, on remet tout en place. C’est une des clés de la méthode. Si vous ne le faites pas, vous n’appliquez pas la méthode Mikado. Pour être transparent, j’ai tenté de ne pas le faire, de prendre des raccourcis, d’aller trop vite. Je me suis perdu et cela ne m’a pas aidé.

Revenir en arrière est très puissant. On n’a pas expérimenté pour rien, on a appris des choses. On se pose des questions pour continuer. Qu’est-ce qui me bloque ? Que faut-il faire pour débloquer cette étape ? On va construire la suite de notre chemin grâce à cette expérimentation échouée et on pourra revenir sur cette étape plus tard, dans de meilleures conditions pour réussir.

Si on arrête là, tout fonctionne. Toujours. Parce qu’on garde les expérimentations qui ont réussi et on retourne en arrière lorsqu’elles échouent.

Dessiner un graphe pour visualiser

Vous ne le voyez pas en lisant l’histoire, mais un graphe a été créé et modifié au fil des expérimentations. C’est un outil essentiel dans l’utilisation de la méthode Mikado qui permet de visualiser l’avancée. On voit ce qu’on a fait, ce qu’on a tenté, ce qu’il reste à faire. On sait facilement à quel point on se situe. On pourra reprendre aisément plus tard ou se faire aider par d’autres personnes. Oui car c’est également un très bon support pour communiquer, pour expliquer ce que l’on fait, pour avoir un coup de main.

La création du graphe

Dessiner un graphe avec la méthode Mikado est très simple. On commence par écrire l’objectif tout en bas dans un double cercle.

On ajoute ensuite un cercle pour chaque expérimentation que l’on réalise, au-dessus du pré-requis précédant, et on les relie à l’aide d’une flèche. La flèche pointe vers le ou les pré-requis à effectuer au préalable - il faut d’abord acheter le Blu-ray afin de le mettre dans le lecteur.

On repère très rapidement les possibles prochaines étapes : il s’agit des pré-requis n’ayant pas de dépendance. On peut alors choisir une expérimentation et essayer.

• Si elle échoue, on ajoutera une ou des nouvelles expérimentations en pré-requis à cette étape.
• Si elle réussie, on cochera l’expérimentation. Ce qui débloquera peut-être d’autres étapes.

Bref, la démarche

Si vous avez bien compris les principes, la démarche ne devrait pas vous surprendre. C’est tout simplement l’application de ces principes coordonnés par le graphe, étape par étape. Dans le livre Mikado Method, il y a un diagramme qui représente très bien les différentes étapes à suivre. Je l’ai recréé ci-dessous.

On commence par dessiner l’objectif sur notre graphe. On essaie ensuite naïvement de trouver une solution. S’en suit une répétition de ces étapes selon le succès de l’expérimentation :

• Dès que l’on bloque ou que notre expérimentation échoue, on dessine les nouveaux pré-requis dans le graphe, on annule les modifications, et on choisit un autre pré-requis.
• Lorsque l’on réussi, on enregistre nos modifications, on commit, et on démarre avec une autre expérimentation du graphe.

On réitère toutes ces étapes jusqu’à atteindre l’objectif. Simple et terriblement efficace.

La dernière brique

On a vu une méthode qui permet de structurer des changements. Même lorsqu’il y a un grand chantier devant nous, la méthode Mikado apporte de la structure en travaillant rigoureusement par petites étapes et expérimentations. Le graphe nous guide tout le long pour arriver à notre objectif, et sert également de support pour communiquer. On ne conserve que ce qui fonctionne et on annule ce qui échoue, ce qui permet d’avoir un projet ou contexte toujours opérationnel.

Et à la fin, il reste toujours une brique Lego ou une pièce du meuble Ikea. Considérez-là comme une dernière chance d’améliorer votre travail une fois que l’ensemble est achevé :)

Avant d’entrer dans les détails, je vous propose de sortir un stylo et une feuille afin de vous poser la question suivante : qu’est-ce que le refactoring ? Faites couler l’encre, gravez votre définition dans les fibres du papier.

Définitions et fondamentaux

Le refactoring demande de la discipline et de l’apprentissage. Il existe des méthodologies, des principes et de multiples techniques. Ah bon, ce n’est pas juste tout refaire ? Non. On voit trop souvent ces fameux « chantiers » qui durent des mois, effectués en silo, sans visibilité et qui ont un résultat peu satisfaisant. Ils auront souvent duré bien plus longtemps que prévu, ou comporteront des régressions, ou seront abandonnés avant la fin. J’en ai vu et j’en vois malheureusement encore. J’en ai également fait, mais depuis, j’ai appris et je continue d’apprendre.

Aujourd’hui, j’ai envie de parler de ce qu’est le refactoring, de ses grands principes. Avant de se lancer dans ces grands chantiers, comprenons de quoi on parle. Je vais m’appuyer sur les définitions de Martin Fowler. Si vous ne le connaissez pas, c’est un des grands noms quand on parle de refactoring. Je vous recommande son site et ses livres.

noun: a change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior.

verb: to restructure software by applying a series of refactorings without changing its observable behavior.

Je vois plusieurs fondamentaux dans ces définitions. C’est bien plus que « tout ré-écrire » ou même que « ré-écrire pour améliorer » (déjà plus précis, mais encore trop simpliste).

Faire du refactoring, c’est conserver le même comportement. Ne pas casser l’existant. Si on change le comportement, ce n’est plus du refactoring. On sépare le refactoring des évolutions et corrections de bugs. Dans le cycle du TDD, il y a une étape dédiée pour le refactoring ; ce n’est pas pendant qu’on écrit le test ni pendant qu’on fait émerger une solution. Lorsque l’on fait du refactoring sur la machine à café, on veut qu’elle continue à faire du café lorsque l’on a terminé. On ne veut pas qu’elle fasse un thé, ni un tiramisu. Et on veut encore moins qu’elle soit en panne.

Faire du refactoring, c’est avancer par petites étapes. On enchaîne une série d’améliorations, on évite de vouloir tout changer d’un coup. Ce sont des petites étapes que l’on peut partager régulièrement. C’est à dire les rendre disponibles aux autres, les committer, les rapatrier sur la branche principale. Ainsi, on peut s’arrêter à tout moment. Si soudainement on doit faire quelque chose de plus prioritaire ou partir en vacances, le projet est toujours dans un bon état et nos petites améliorations seront en plus intégrées. Dans l’hypothèse où les développeurs tirent leurs super-pouvoirs du café, si pendant un mois la machine est en chantier, donc inutilisable, ça posera des problèmes.

Faire du refactoring dans le but d’améliorer la compréhension et de diminuer le coût du changement. On peut vouloir rendre le code plus lisible, avec une intention plus claire, un métier mieux projeté. L’amélioration continue est importante. On peut vouloir également rendre le changement plus facile, donc moins couteux. Ré-écrire uniquement pour le plaisir du développeur d’intégrer le dernier framework X-2000 est peut-être une moins bonne raison. Notre machine à café a besoin d’un refactoring, car elle ne prend en charge qu’un seul type de dosette très précis.

Je pense qu’il est important de prendre conscience de ces fondamentaux et d’être dans cet état d’esprit afin d’améliorer son approche du refactoring. Bien sûr, il reste du chemin ensuite, ce n’est que le début du voyage, mais c’est une étape essentielle.

Aller plus loin

Pour continuer d’approfondir le refactoring, on peut regarder du côté de la détection de code smells, de l’apprentissage des techniques de refactoring, de méthodes pour structurer un refactoring, ou encore de l’art de tester du code legacy (casser des dépendances, introduire des tests, …). Oui, la liste est grande, ce n’est pas si simple. Et oui, il ne faut pas oublier les tests pour s’ajouter un filet de sécurité.

Quelques ressources autour du refactoring :

• Martin Fowler. Une figure incontournable avec son le site refactoring.com et son livre Refactoring Improving the Design of Existing Code.
• Michael Feathers. Une seconde figure incontournable, plus axée sur le code legacy avec son livre Working Effectively with Legacy Code.
• Le site refactoring.guru listant techniques de refactoring et code smells.
• Divers katas pour s’exercer comme le Gilded Rose, Tennis Game, Trivia, etc.
• Ici même, avec le temps, via le tag #refactoring.

Seconde édition

Vous avez toujours le bout de papier avec votre première définition ? Reprenez-le. Je vous propose d’écrire une nouvelle fois ce que représente le refactoring pour vous pour terminer. Au dos de la feuille ou sans relire les définitions a minima.

Amusez-vous à comparer les trois définitions maintenant. Et si le cœur vous en dit, partagez-moi vos écrits :)

Cet été, j’ai eu un bug à corriger sur une partie de l’application que je n’avais pas encore touché. Après une brève balade dans le code, je tombe sur le RoadMapBlock. Le fameux RoadMapBlock. Ça ne vous parle certainement pas, mais en interne, ce nom possède une grande renommée. Ce nom-là, je l’ai entendu lors de mes premiers jours. Son évocation suscitait rires nerveux et désespoir. Il est même connu des non-tech, c’est dire. Mais de quoi bon s’agit-il ?

Le RoadMapBlock est à la fois une brique centrale pour l’un des écrans les plus importants de l’application et l’un des gros points de douleurs du projet. Cette brique a été créée des années auparavant et a depuis été modifiée par des dizaines de développeurs. Pour donner un ordre d’idée, la classe possède une centaine de fonctions. La méthode qui contenait le bug faisait avoisinait le millier de lignes et possédait une grande complexité (une centaine de ifs, plusieurs niveaux d’imbrications, des boucles, …).

Une horreur à première vue, mais également une énorme opportunité d’amélioration.

Faire du refactoring progressivement

J’ai commencé ma session de travail par la localisation de l’erreur dans le code. Je sentais qu’il se passait quelque chose dans une partie de cette fonction, mais la zone était difficilement intelligible. Je me suis donc mis à faire du rapide refactoring pour gagner en compréhension. J’ai effectué plusieurs opérations de refactoring pour améliorer le code, me l’approprier, et y voir plus clair. C’est un moyen rapide de comprendre du code legacy que j’aime bien utiliser (j’en parle plus en détails dans mon précédent article). Peu de temps après, la cause du bug me sautait aux yeux et j’ai pu le corriger facilement. La correction tenait en une seule ligne. Mais était-ce fini ? Non !

J’étais là, au milieu de tout ce code legacy. J’avais pris du temps pour en comprendre une partie, pour l’analyser, pour charger tout ce contexte dans ma tête. J’avais même effectué des modifications ici. Alors autant en profiter pour améliorer le code, pendant que j’étais encore plongé dans ce contexte. Il ne faut pas sous-estimer ce moment. La compréhension du code legacy est souvent difficile et longue. Ce n’est pas non plus quelque chose qui motive, ou qui donne envie, pour la plupart des développeurs. Il faut sauter sur l’occasion pour l’améliorer. Il y a peu de chances qu’on se réveille un matin en se disant « tiens, je vais refaire cette partie pour le plaisir ». Si on ne le fait pas là, maintenant, on ne le fera probablement jamais. Ce code qui nous fait si mal restera une épine dans notre pied.

J’ai donc recommencé mon refactoring proprement. Mon gain de compréhension me permettait de mieux le faire. J’ai renommé des variables, des noms de méthodes. J’ai extrait des méthodes pour commencer à découper et à structurer. J’ai diminué les niveaux d’imbrications des ifs, switch, et for. Des actions simples qui aident énormément pour le futur. Oui, pour le futur. On lit beaucoup plus de code que l’on en écrit. Faire du refactoring maintenant permettra de mieux comprendre ce code toutes les autres fois.

C’est également une fondation pour un refactoring plus large. La succession des petites améliorations facilitent un refactoring plus conséquent. Un jour, il sera aisé de tout reprendre. Le refactoring d’une fonction complexe de mille lignes demande un gros effort. Mais cette même fonction, découpée en plusieurs petites fonctions simples, mieux nommée, mieux structurée, est bien plus facilement modifiable. Peut-être même que ce ne sera plus nécessaire, la structure du code sera peut-être suffisamment bonne pour être comprise et pour évoluer.

L’amélioration du code qui entoure nos modifications peut aller très vite. Je n’ai pas dû prendre plus d’une heure. Une heure sur la vie d’un projet, ce n’est rien. Pourtant, ça a une immense importance. C’est un gros gain. On agit maintenant, on passe à l’action. C’est facile de se plaindre du code legacy, c’est aussi facile de faire des améliorations par petits pas. Cependant, se plaindre ne fera pas avancer les choses.

Savoir s’arrêter

On est enfin lancé dans ce refactoring, on veut bien faire. On peut avoir envie de faire quelque chose de parfait. Ou de tout refaire. Mais l’important, c’est de commencer à améliorer, par petits bouts, et de le faire régulièrement. Il est plus facile d’être régulier en faisant des petits refactoring. Avec le temps, ce deviendra un automatisme. Je fais une modification ici, je vais en profiter pour améliorer là. La qualité globale du projet augmentera progressivement.

L’objectif n’est pas de faire quelque chose de parfait. Ce serait trop long. Dans certains cas, le legacy est tellement grand qu’il faut effectuer de nombreux changements. Malheureusement, certains changements sont longs et complexes. Casser des dépendances. Changer la structure du code. Et puis, qu’est-ce que le code parfait ? On peut toujours améliorer et faire différemment. Le design du code peut faire grincer des dents, mais ce n’est pas grave, c’est mieux qu’avant.

L’objectif n’est pas de tout refaire. Ce serait risqué et également long. Si on veut tout réécrire d’un coup, le travail sera énorme et probablement risqué. On peut faire de grosses erreurs, rater le refactoring. On peut découvrir de nombreux problèmes en cours de route et prendre beaucoup plus de temps que prévu. Pire, on peut abandonner avant même d’avoir terminé. Tout le travail serait alors jeté. L’équipe ou le management pourrait accorder plus difficilement sa confiance pour d’autres sujets. Il est préférable de bien cibler la partie que l’on veut améliorer à cet instant.

Il faut donc savoir s’arrêter à un moment. Se concentrer sur des petites améliorations. C’est déjà mieux qu’avant. Si on y revient plus tard, on pourra à nouveau l’améliorer. Voire améliorer de manière plus macro. J’ai espoir que mon refactoring d’une petite zone du RoadMapBlock servira de première étape à l’amélioration de l’ensemble. La première pierre à l’édifice. Ce travail continuera et inspirera les autres développeurs.

Lancez-vous, maintenant

Toutes les améliorations sont intéressantes. Du simple renaming ou suppression de code mort à l’extraction de méthodes ou restructuration. Les améliorations peuvent être simples et effectuées rapidement. Il n’y a pas d’excuse à rester sans rien faire devant du code legacy. Il n’y a pas besoin de tout refaire, ni d’y passer des journées entières.

Faire de petites améliorations et être régulier. C’est une des clés pour sortir du legacy progressivement. Profitez d’une correction de bug ou d’une évolution pour améliorer le code environnant. Passez à l’action dès maintenant.

Et vous, que faites-vous pour améliorer du code legacy ? Quelles sont vos stratégies ?

C’est un phénomène commun. Le code legacy s’entoure d’une perte de connaissance technique et métier. L’équipe ne comprends plus ce qui se passe dans le code, et ne sait plus trop ce que ça doit faire fonctionnellement.

Dans ces moments-là, la seule réponse restante se trouve dans le code. Le code est la seule vérité. La vérite d’un programme en production. Mais comprendre du code legacy est difficile. Alors comment le faire parler ? 

Mes deux méthodes préférées sont le dessin et le Refactoring. Encore récemment, j’ai utilisé le refactoring pour gagner en compréhension, et ça m’a donné envie d’écrire sur ce sujet.

Gagner de la compréhension

Si modifier du code pour mieux le comprendre vous surprend, regardons une définition (simple) d’un refactoring : c’est améliorer le code sans en changer le comportement. Rendre du code plus lisible, plus facile à comprendre, c’est améliorer le code. C’est exactement ce que l’on cherche.

Lorsque je bloque sur un bout de code, je le modifie. J’essaie de me l’approprier, de gagner en compréhension. Si je casse quelque chose ce n’est pas grave, je retourne en arrière avec Git ou tout autre VCS.

Qu’est-ce que l’on peut faire comme type de refactoring ? Je dirais tout ce qui nous aide. Pour illustrer mon utilisation des différentes techniques de refactoring, j’ai écrit une petite fonction. Ce sera notre legacy.

fun hit(p1: Player, p2: Player) {
    var name = "King"
    if (p1 != null && p2 != null) {
        if (!(p1.firstName == "Arthur" && p1.lastName == "Pendragon" && p1.weapon.name == "Excalibur")) {
            var multiplier = 1
            if (p1.lord) {
                multiplier = 7
                // will multiply the power!!
                var power = p1.strength * multiplier
                p1.strength += 10
                power = p1.strength
            }
            var health = p1.strength + p1.weapon.damage
            if (p2.shield != null && p2.shield.defense > p1.weapon.damage && p2.speed > p1.speed + 1) {
                health = health / 2
            }
            p1.weapon.worn += 1
            p2.health -= health
        } else {
            p1.kill(p2)
        }
        // ...
    }
}

Je commence souvent par des actions simples comme renommer. Renommer une variable, une fonction, une classe. Je fais également du nettoyage : en supprimant du code non utilisé, j’enlève le superflux.

fun hit(attacker: Player, target: Player) {
    if (attacker != null && target != null) {
        if (!(attacker.firstName == "Arthur" && attacker.lastName == "Pendragon" && attacker.weapon.name == "Excalibur") {
            if (attacker.isLord) {
                attacker.strength += 10
            }
            var damage = attacker.strength + attacker.weapon.damage
            if (target.shield != null && target.shield.defense > attacker.weapon.damage && target.speed > attacker.speed + 1) {
                damage = damage / 2
            }
            attacker.weapon.worn += 1
            target.health -= damage
        } else {
            attacker.kill(target)
        }
        // ...
    }
}

J’aime bien inverser les if. J’ai parfois du mal à lire les conditions négatives, notamment lorsque la condition est complexe. Je dois d’abord comprendre la condition, la mapper mentalement, puis je vois la négation, j’inverse cette logique complexe… pour finalement me perdre. Parfois même je loupe ce tout petit caractère, ce point d’exclamation collé trop près de la variable. Alors j’inverse. La condition gagne en clarté, je sais pourquoi on passe dans le corps du if, et au passage ça peut permettre de réduire les niveaux d’imbrication.

fun hit(attacker: Player, target: Player) {
    if (attacker == null || target == null) return
    
    if (attacker.firstName == "Arthur" && attacker.lastName == "Pendragon" && attacker.weapon.name == "Excalibur") {    
        attacker.kill(target)
    } else {
        if (attacker.isLord) {
            attacker.strength += 10
        }
        var damage = attacker.strength + attacker.weapon.damage
        if (target.shield != null && target.shield.defense > attacker.weapon.damage && target.speed > attacker.speed + 1) {
            damage = damage / 2
        }
        attacker.weapon.worn += 1
        target.health -= damage
    }
    // ...
}

Je cherche aussi à mieux structurer et à découper pour réduire la charge mentale nécessaire pour comprendre. Je parlais des if juste avant, j’aime bien faire un extract method pour rendre la condition explicite. J’utilise aussi le extract method dans le corps des grandes fonctions, ou dans les boucles. Le code est plus lisible, la fonction est plus courte, et j’ai une indication sur son intention. Je gagne en compréhension.

fun hit(attacker: Player, target: Player) {
    if (attacker == null || target == null) return
    
    if (isArthurWithExcalibur(attacker)) {    
        attacker.kill(target)
    } else {
        if (attacker.isLord) {
            attacker.strength += 10
        }
        inflictDamage(attacker, target)
    }
    // ...
}

Pour une restructuration encore plus poussée, il m’arrive quelque fois de faire un extract class ou un move method afin d’organiser davantage les fonctions et d’améliorer la lisibilité. Par exemple, ici j’aurais pu déplacer quelques méthodes ou créer des extensions sur la classe Player. Le design du code serait amélioré, mais ce ne serait pas forcément d’une grande aide pour ma compréhension immédiate. Il faut savoir quand s’arrêter.

Avec ce type de modifications, je suis passé d’une zone très dense de 3000 lignes (difficile à mapper mentalement, avec beaucoup de choses superflux pour mon contexte) à quelques petites fonctions (bien mieux pour ma charge mental). J’ai pu recentrer mon effort sur les morceaux qui m’intéressaient le plus.

Bien sûr, il existe tout un tas d’autres techniques de refactoring. Les sites refactoring.com et refactoring.guru proposent un aperçu intéressant. Si vous voulez approfondir, je vous recommande de lire le livre Improving the Design of Existing Code de Martin Fowler ou Working Effectively with Legacy Code de Michael Feathers.

Prendre des libertés

Je ne conserve pas forcément mes changements. Parfois, mon objectif principal est le gain de compréhension. Le refactoring est un moyen pour y parvenir, ce n’est pas la finalité. Il m’arrive donc de prendre des libertés avec le code que j’écris.

Je n’essaie pas de faire le meilleur code possible, ni le meilleur design. Je m’autorise par exemple à passer des paramètres en inout par simplicité. Créer des fonctions avec de nombreux paramètres ne me dérange pas non plus.

Je ne fais pas de tests unitaires garantissant que mes modifications ne changent pas le comportement. Encore une fois, mon but est de comprendre. Je ne compte pas garder ce code, donc le comportement ne sera pas altéré.

Ces prises de libertés me permettent d’obtenir rapidement une meilleure compréhension globale d’un morceau de code legacy. Le retour en arrière est facile avec Git. On efface tout ou on utilise une autre branche (permettant de faire des petits commits de compréhension).

Faire attention

Le refactoring est une discipline. Conserver le même comportement est primordiale. Même lorsque les modifications sont destinées à être effacées, il faut faire attention à ne pas faire une grosse erreur qui fausserait notre compréhension en allant trop vite.

Pour minimiser ce risque, j’utilise au maximum des techniques de refactoring sûre, et je conserve les mêmes signatures pour avoir des vérifications au niveau de la compilation. Certains IDEs proposent également des actions de refactoring automatisées qui évitent des erreurs humaines.

Si vous prenez des libertés pour aller plus vite et que vous prévoyez d’abandonner le code, abandonnez-le. Ne vous y attachez pas. Avec la compréhension que vous aurez acquises, votre second refactoring sera encore meilleur.

Bref

Je me sers du refactoring pour faire émerger de la compréhension. Pour rendre le code plus lisible, pour voir l’intention. C’est relativement rapide et extrêmement efficace. Je m’approprie le code et c’est un point de départ intéressant pour améliorer le code legacy.

Je fais également émerger des points de douleurs, ou des zones qui soulèvent de grandes questions. C’est tout aussi important pour identifier d’éventuels problèmes à venir et les partager au reste de l’équipe.

La prochaine fois que vous tombez sur une zone difficile, essayez de faire un petit refactoring. C’est à la portée de tous, sur tous les langages et plateformes. Le refactoring est une discipline connue, de même que les techniques utilisées. Vous avez juste à y penser, et à essayer.

Et vous, que faites-vous pour comprendre du code legacy ? Quelles sont vos techniques ?

Having too many warnings can be discouraging, and there is also a bigger problem: too many warnings kill the warning. If you start to write code before resolving SwiftLint issues, you may miss some new important problems. So, let’s see how you can handle that.

Quarantine strategy ☣️

Most of the violations can be fixed without problem, but there are many. Then there are more complex issues. Some violations will need refactoring.

You will need time to handle every warning, and you have to take time. Do not go fast, do it well. As you may not fix everything at once, you will have to do it progressively. But how? How can we take time and live with so many warnings?

Our strategy will be to isolate infected files and exclude them, then to fix violations and files over time. This strategy also plans to visualize progress and prevent regressions.

Autocorrect is our magic wand

Before you start the quarantine, you can run the swiftlint autocorrect command. Only a handful of rules can be automatically corrected, but it is pretty efficient and it can save you a lot of time and effort.

Autocorrecting is the easiest part. It is automatic, and it is mainly dealing with spaces and indentations. Be sure to check changes after running the command.

Exclude infected files

More than a thousand of warnings on dozens of files. That’s what you can have. The goal of this step will be to fall to zero violation, as if there were nothing, but without fixing.

The idea of quarantine is to exclude all infected files from the analysis. An infected file is a file containing at least one violation. Only healthy files and new files will be linted.

In order to make the job easier, I wrote a script to list all infected files in a project. It will run SwiftLint, extract paths, and even format the output list.

#!/bin/bash

current_pwd=`pwd`
escaped_pwd=$(echo "$current_pwd" | sed 's/\//\\\//g')

# run swiftlint, grep to filter only lines with .swift, sed to extract paths, sort to group paths, sed to remove first slash, sed to add

Pods/SwiftLint/swiftlint | grep .swift: | sed 's/^\([^:]*\):.*/\1/' | sort -u | sed "s/$escaped_pwd//" | sed 's/^\///' | sed 's/\(.*\)/- \1/'

This script assumes that you did install SwiftLint in your project with cocoapods, and that you put the script in the root folder of your project. Feel free to change paths. The output of your terminal will look like that:

Loading configuration from '.swiftlint.yml'
Linting Swift files at paths
Linting 'ArticleListViewController.swift' (1/464)
Linting 'ArticleViewController.swift' (2/464)
...
Linting 'Widget.swift' (464/464)
Done linting! Found 336 violations, 30 serious in 464 files.
- MyApp/Article/ArticleListViewController.swift
- MyApp/Article/ArticleCell.swift
...
- MyWidget/Widget.swift

The first part is printed by SwiftLint. It is telling you which files are analyzed. The second part is the list of infected files with the relative path. This list is formatted. You will just have to copy and paste the result in the configuration file .swiftlint.yml under `excluded keyword. You may have to indent it.

excluded:
— Pods
- MyApp/Article/ArticleListViewController.swift
- MyApp/Article/ArticleCell.swift
...
- MyWidget/Widget.swift

From now on, the number of warnings is zero and we are preventing problems on healthy files. A warning will appear as soon as a code will violate a rule on these files. And that’s because SwiftLint is still integrated, enabled and fully configured with the rules you choose.

Only infected files at the quarantine creation are excluded. Their warnings are hidden and you will be able to handle them progressively. This step is performed only once, you may not have to exclude new files. We can imagine doing another quarantine if a change causes a lot of warnings (changing your rules or updating SwiftLint for example).

Treat infected files

Each time you have to edit an infected file, take the opportunity to correct few violations. Sometimes, you can also choose to pick a file and to treat all of its problems at once. Do not forget to remove a file from the excluded list when it becomes healthy.

Try to decide how you can take time to reduce warnings over time. Discuss about it with your team, with the other developers and also with your Product Owner or your manager. It can be for example two hours every Monday morning.

Visualize your progression

When you have hundreds or thousands of violations, it is helpful to know where you are and how numbers are evolving. It will also motivate your team to decrease the total of warnings.

You can create a second SwiftLint configuration file without excluded files in order to lint everything. Give it a different name, and specify it when running the swiftlint command: swiftlint --config .swiftlint-full.yml.

Your basic configuration is used to show you warnings through Xcode, without files in quarantine, and your CI or an other tool can execute SwiftLint with the second configuration in order to have a global vision. This way, you can make charts or have the current count to follow your progression.

In a dedicated article about SwiftLint, I wrote a part about the power of visualization. You can find how to easily have charts with Jenkins, or with a sheet of paper if you do not have any CI.

Forbid regression

While you are healing infected files, and even when the whole project is healthy, you should prevent new violations. Do not add new errors when you are writing code.

For that, set up your CI to fail a build if there is new lint errors. You may otherwise want to take a look at pre-commit git hooks, to forbid a commit containing violations, or at Danger to have automatic messages on your pull requests.

It is also helpful to use a second SwiftLint configuration here, linting infected files, to see hidden warnings. Remember that the quarantine disable analysis on infected file. So you need something to warn you if you are adding new violations inside these files.

Alternative ideas 🔀

Disabling rules

The principle of this quarantine strategy is to exclude from analysis each files containing at least one warning or error. Another possibility is to disable every of your rules in your configuration file.

This way, you will end up with zero violation. You can then re-enable a rule and fix corresponding warnings. One rule by one rule. It will give you the flexibility to correct problems progressively. The counterpart is that you will disable rules for every files, even healthy files or new ones.

Nested configurations

You can also profit nested configurations with SwiftLint. You can put different configurations in subfolders. Thanks to that, you can choose to specifically enable or disable rules in your project hierarchy.

We can even imagine combining both approaches: putting some files in quarantine, and disabling certain rules on specific subfolders.

Make your code consistent, and go further

If you want to know more about code consistency and how to unleash the power of SwitLint, you can read two of my previous articles:

• Make your code consistent
• Unleash the power of SwiftLint

And that’s all for now 👋

Thanks for reading. Feel free to make any feedback and to open discussion. Let’s finish with you. How are you using SwiftLint? Do you have any tips to share when you have too much warnings? What did you learn?