Retour

Comment lutter contre l’entropie ?

Introduction

Que cela votre chambre ou votre base de code, toute chose est soumise à l’entropie : nous allons toujours de l’ordre vers le désordre. Cela dit, il existe un certain nombre d’outils et stratégies pour limiter et contrôler ce phénomène. Passons-les en revue au travers de problèmes concrets.

Mais que fait le back-end ?!

Ne vous est-il jamais arrivé de vous retrouver bloqué par le back-end car vous ne saviez pas quel était le format de réponse attendu ? Ou même, de ne pas avoir de documentation du tout et de devoir regarder le code vous-même pour comprendre certaines incohérences ? Parfois, lorsque vous codez sur les deux fronts, il vous est probablement aussi déjà arrivé de mettre à jour une interface d’un côté et d’oublier de le faire de l’autre.

Une méthode pour remédier à ces problèmes est d’adopter une méthodologie de travail basée sur le contrat [Contract-First Development].

Le principe est le suivant : au lieu de commencer à coder à partir des demandes du client puis de générer (lorsqu’on y pense, ou de façon automatique) la documentation de l’API, on commence par définir un contrat en collaboration avec tous les membres de l’équipe, puis, à partir de cette base qui deviendra la source de vérité unique pour la structure de l’API, les développements pourront commencer.

Voici un exemple concret et quelques outils pour mettre en place cette méthode de travail :

  1. Définition de l’API : la première chose à faire est de rédiger votre contrat. Celui-ci est conventionnellement rédigé en suivant la spécification OpenAPI. Vous pouvez au choix retrousser vos manches et l’écrire au format JSON (le format YAML est beaucoup plus pénible à écrire et peut vous causer des coucis) ou bien utiliser un outil externe pour faciliter le processus. Il existe une quantité importante d’outils graphiques (cf :GUI editors) ainsi que d’autres solutions comme TypeSpec pour générer votre contrat ; à vous de tester et de voir ce qui vous convient le mieux.
  2. Données factices et générations : comme la forme des données a été discutée et formalisée, il est maintenant possible pour l’équipe front-end de travailler avec des données factices en attendant le back-end. Une façon efficace de faire est d’utiliser une bibliothèque comme MSW pour intercepter les requêtes, et en conjonction Faker pour générer les données factices (ne sous-estimez pas cet outil : rédiger de telles données à la main est laborieux et la mise à jour de ces dernières prend également du temps).
    Les logos des bibliothèques MSW et Faker. L’avantage d’avoir commencé par rédiger votre contrat avec OpenAPI est que vous pouvez même vous dispenser de l’effort de rédiger le code pour générer les données factices en utilisant des générateurs. Ces derniers vous permettent, en donnant en entrée un fichier OpenAPI (au format .json ou .yaml) de générer automatiquement tout un tas de choses utiles comme les types et DTO de vos objets, de la documentation, des données factices et même vos fonctions pour appeler votre back-end si vous utilisez TanStack Query. Il en existe à ma connaissance trois principaux :
    • openapi-generator : probablement le générateur le plus connu.
    • swagger-codegen : le générateur officiel par SmartBear. Nécessite java pour le faire fonctionner.
    • Kubb : un projet qui ne semble pas aussi connu que les deux autres précédemment cités, mais dont le nombre important de plugins en fait un outil à considérer sérieusement.
  3. Partage du contrat : vous avez votre contrat et même généré des utilitaires au moyen de clui-ci ; comment le partager aux différents membres de l’équipe à présent ? Deux choix principaux :
    • Si vous travaillez dans un monorepo, vous pouvez utiliser le système de workspaces (disponible sur pnpm, bun et npm) et placer votre contrat dans un dossier shared.
    • Vous pouvez créer un dépôt séparé pour gérer votre contrat et ensuite publier sur le registre de votre choix (GitLab Package Registry ou npm)
  4. Aller plus loin : je n’ai fait que dessiner cette méthodologie dans les grandes lignes, mais il est possible de faire beaucoup plus. Vous pouvez notamment explorer OpenAPI.Tools pour découvrir d’autres outils et fouiller du côté des tests de contrats pour découvrir un autre paradigme de test.

Guerre de formatage

De manière assez surprenante, le formatage et la vérification [linting] du code est souvent un sujet sur lequel les équipes perdent du temps et où peuvent naître des tensions. Combien de sang n’a pas coulé durant l’éternelle guère entre la tabulation et l’espace ?

Daffy Duck and Bugs Bunny se querellant pour choisir s’il faut utiliser une espace ou une indentation.

Prettier et ESLint (respectivement utilisés pour le formatage et la vérification du code) sont les deux outils de référence dans l’écosystème JavaScript pour remédier à ces problèmes.

Ne perdez pas de vue que le problème principal à résoudre est l’homogénéité du code, c’est pourquoi la question du meilleur outil ou formatage ne doit pas entrer en compte.
Assurez-vous simplement que votre linter ou formateur prenne bien en compte tous les cas de figure que vous pourrez rencontrer (ce que est généralement le cas avec le combo ESLint/Prettier, comparé à d’autres outils comme Biome qui par exemple ne permet pas de formater le code HTML, SCSS ou Vue au momement où j’écris ces mots).

Une autre question qui arrive est ensuite celle de l’utilisation de ces outils. Comment utiliser Prettier et ESLint de sorte à ce que le code soit toujours vérifié et formaté ? J’y répondrai avec cette maxime que j’estime être vraie, y compris au-delà du développement :

Ne demandez pas aux hommes de faire le bien : empêchez-les de faire le mal.

Ne faites confiance à personne : ni aux utilisateurs, ni aux développeurs, ni à vous-même ! Si vous demandez aux développeurs d’utiliser leurs IDE [environnement de développement], rien ne vous assure que la configuration sera identique sur tous les postes, que tout le monde utilisera le même IDE ou pensera à installer toutes les extensions.

La seule façon d’être assuré de la vérification du formatage et de la vérification du code est de lancer les scripts respectifs à ces outils sur votre pipeline (idéalement lorsque vous faites une demande de fusion).

Pour détecter les erreurs en local plus rapidement, vous pouvez bien entendu utiliser les outils de votre IDE ou, après discussion avec les membres de votre équipe, ajouter des pre-commit hooks pour vérifier votre code à chaque commit (vous pouvez les mettre en place au choix avec Husky et lint-staged, des outils éprouvés, ou bien lefthook, plus récent mais qui fonctionne bien et qui ne nécessite pas d’installer lint-staged pour détecter les fichiers indexés par Git).

Notez cependant que les pre-commit hooks ne remplacent pas la pipeline : comme je l’ai écrit plus haut, vous ne devez faire confiance à personne. Les pre-commit hooks offrent un certain confort de développement en local mais ils peuvent facilement être outrepassés.

Le code CSS est inmaintenable !

Contrairement au code JavaScript qui reçoit toujours un minimum d’attention, le CSS est très souvent négligé et par le fait qu’il ne ne bénificie pas de la sécurité de typage de TypeScript, le code mort est très fréquent, les erreurs faciles à faire et l’ordre difficile à étabir.

Il existe cependant un outil permettant de vérifier votre code CSS de la même manière que votre code JavaScript avec ESLint : stylelint. Voici une liste des plugins et fonctionnalités les plus pratiques :

Il y a des fautes de frappe partout !

Vérifier l’orthographe de votre projet (que cela soit les commentaires, le contenu du README ou le nom de vos variables) est un autre élément qu’il ne faut pas négliger. Un outil de choix pour contrôler ce point est CSpell. Pour plus de commodité, vous pouvez l’utiliser via un plugin ESLint (@cspell/eslint-plugin) et en complément utiliser une extension pour VSCode (Code Spell Checker).

Suppléments

En guise de supplément, voici une liste de quelques plugins ESLint et Prettier que j’apprécie (certains seront peut-être disponible nativement au moment ou vos lisez ces mots) :