HackMD - Collaborative Markdown Knowledge Base

### TL;DR *L'objectif de ce document est d'exposer les bénéfices liés à l'intégration de Typescript dans nos projets.* - *Nous avons rencontrés trop de problèmes en production qui aurait pu être évités simplement, avec du typage* - *Typescript apporte beaucoup d'avantages : Sécuriser la maintenance, améliorer la productivité sur le long terme, renforcer la conception, expliciter et homogénéiser le code* - *On peut aussi lui voir des inconvénients : maintenance des types nécessaire et difficultés de débogages* - *Nous pensons que la mise en place de Typescript serait moins chronophage que la maintenance d'un code non typé* - *Des stratégies existent pour échelonner l'intégration de Typescript* ## Motivation Après de longues discussions et échanges entre nous autour de Typescript, nous nous sommes rendus compte des avantages que Georges pouvait tirer de son utilisation. Ce sentiment a récemment été renforcé par différents problèmes que nous avons eu en production et qui auraient été facilement détectables en amont avec typescript (propriété inexistante sur un objet, appel de fonction avec une signature fausse, etc). Si les tests sont censés résoudre une partie de ces problèmes, force est de constater que ça ne marche pas toujours et que certaines erreurs sont assez fourbes. Nous avons donc décidé d'écrire ce RFD dans l'optique d'ouvrir et d'officialiser le dialogue sur ce sujet à l'ensemble de l'équipe technique. Les différents points que vous trouverez ci-dessous sont tirés de notre expérience passée, de notre (modeste) expérience sur Georges mais aussi d'échanges avec différents développeurs ayant utilisé TS. L'espoir est que cela nous permettra de faire évoluer la base de code de l'entreprise bien au-delà de la taille de notre base de code actuelle, tout en gardant le code facile à comprendre et maintenir. ## Avantages attendus  ### Sécuriser la maintenance Avoir un système de typage peut nous faciliter et aider à sécuriser la maintenance. _Sécuriser, mais bien évidemment en **complément** des tests unitaires que l'on a déjà l'habitude de faire._ Devoir modifier la signature d'une fonction est une situation courante. Par exemple, lors de la mise en place de l'exercice décalé, préciser une année fiscale ne suffisait plus pour déterminer la période fiscale. La signature de plusieurs fonctions a alors dûe être modifiée. Avec notre base de code en JS, comment s'assurer que tous les appelants de la fonction modifiée ont correctement été mis à jour ? TypeScript nous apporte une sécurité supplémentaire dans ce cas précis, et à un coût ridicule : Prenons par exemple ce changement, dans lequel on rajoute la date de fin d'exercice fiscal pour pouvoir créer une OD à la bonne date : ```diff - personalReintegrationTransaction(asset, lastFiscalYearOpen) { + personalReintegrationTransaction(asset, lastFiscalYearOpen, endDate) { ``` Il faut donc changer tous les appels à cette fonction pour lui fournir cette fameuse date. Mais que se passe-t-il si l'on oublie ce paramètre ? _Rien._ Cet appel est totalement valide et `endDate` sera simplement `undefined` dans le corps de la fonction : ```js personalReintegrationTransaction(asset, lastFiscalYearOpen) ``` `moment(undefined)` donne la date courante, et par conséquent toutes les OD sont créées à la date du jour, et donc très souvent en dehors de l'exercice fiscal pour lequel cette OD était destinée. Il faut donc prévoir un script de correctifs pour replacer ces OD aux bonnes dates, avec toutes les conséquences que cela implique (notamment quand l'exercice est déjà clôturé). ***Comment TypeScript aurait pu éviter le problème ?*** Même sans _aucune_ annotation de type, cette erreur aurait été détectée, rien qu'en se basant sur le nombre de paramètres. Cet exemple, bien que trivial, montre que TypeScript est là pour nous **aider**, pas pour ralentir notre cycle de développement. Par défaut, le compilateur est déjà capable de nous donner des retours utiles, alors imaginez si l'on aide le compilateur en lui précisant les types attendus et les formats de données ! À mesure que Georges grandit, et par extension son équipe, il sera de plus en plus difficile pour nous de s'assurer que de tels changements n'introduisent pas de bugs. ***TypeScript ne résoudra pas tous les problèmes, mais peut nous aider à en prévenir beaucoup.*** D'après une estimation d'Airbnb sur leurs bugs rencontrés en production avant leur migration vers TS, **38% des bugs seraient évitables avec TS**. Cette sécurité supplémentaire nous permettrait par ailleurs d'appliquer la technique du "boyscout" avec plus d'assurance et de sérénité, réduisant ainsi les barrières pour des petits refactorings courants pouvant améliorer la qualité globale du code.  ### Productivité Bien que cette idée puisse paraître contre intuitive parce qu'il faut définir et maintenir des types, nous pensons qu'elle peut au contraire fluidifier les développements. Détecter les erreurs potentielles plus tôt dans la feedback loop évite d'avoir à exécuter le code en testant l'app trop souvent, en faisant des aller-retours entre le navigateur et les sources. On réduit alors le nombre de changements de contexte qui réduisent la productivité. Par ailleurs, les IDE s'intègrent extrêmement bien avec TS en fournissant de l'autocomplétion et l'affichage d'erreurs instantanément dans les sources. Ce qui fait qu'il n'est pas nécessaire d'exécuter le compilateur TypeScript manuellement pour savoir si l'on a fait des erreurs (comme pour ESLint). On alors l'assurance d'avoir une documentation à jour avec l'implémentation, utilisable par les IDE. <details> <summary>Petit exemple avec les amortissements</summary> Prenons le cas de cette fonction permettant de calculer les plus-value et moins-value d'une immobilisation : ```js function calculateGainLoss(args) ``` Aujourd'hui, il est difficile de dire quels sont les arguments attendus et quel est le retour de cette fonction. Dans ce cas, on doit regarder l'implémentation pour comprendre comment se servir de la fonction. Voilà comment est-ce que l'on pourrait typer cette fonction : 1. Tout d'abord, on définit ce qu'est un `asset` : ```ts type Asset = { id: string date: Date user: UserInfo // { user: { _id: string } } amortizations: Amortization[] // --snip-- } type Amortization = { year: number amount_in_cents: number personal_kilometer_option_amount_in_cents: number // --snip-- } ``` 2. Ensuite, on peut mettre à jour la signature de la fonction : ```ts function calculateGainLoss({ asset: Asset, date: Date, amount: number, shortTermOnly: boolean, startDate: Date, endDate: Date, }): { gainOrLossSTInCents: number, gainOrLossLTInCents: number } ``` Avoir une fonction bien définie comme ici nous permettra de faciliter les futurs refactos lorsqu'elles seront nécessaires, car le compilateur pourra vérifier que tous les paramètres sont passés correctement. D'ailleurs cela tombe bien, rajouter une notion de startDate et endDate pour gérer les utilisateur en exercice décalé. Par exemple, on peut imaginer que donner une `startDate` et `endDate` pour un exercice fiscal est une chose courante avec les exercices décalés, pas uniquement dans ce contexte. On peut donc définir un nouveau type qui encapsule ces valeurs : ```ts type ExerciseDates = { startDate: Date endDate: Date } ``` et changer la définition de la fonction comme ceci : ```diff function calculateGainLoss({ asset: Asset, date: Date, amount: number, shortTermOnly: boolean, - startDate: Date, - endDate: Date, + exerciseDates: ExerciseDates, }): { gainOrLossSTInCents: number, gainOrLossLTInCents: number } ``` Grâce une définition explicite des types, on peut donner un sens aux paramètres au-delà des types par défaut, rendant ainsi notre signature plus compréhensible et notre interface plus claire.maintenant ainsi le code en état de marche </details> ### _Program to interfaces, not implementation_ Attention, on ne parle pas forcément du mot-clé `Interface` du langage, mais plutôt du _concept_. Au moment de l'écriture d'une nouvelle fonction, il peut être utile de se poser la question des pré-conditions (les paramètres et leurs types) et des post-conditions (quoi retourner et sous quel format). Cela constitue donc en quelque sorte l'interface, ou la signature de cette fonction. En précisant le contrat d'une fonction avec des annotations de types cela nous force à réflechir en amont, et espérons-le, à faire moins de suppositions sur le contexte des appelants. L'implémentation est alors en quelque sorte "libérée" du contexte des appelants, il suffit alors de satisfaire la signature. Cela pourra plus nous inciter à découpler nos différentes briques. Au final, cette idée reprend un peu celle du TDD : d'abord **quoi**, ensuite **comment**. ### Rationalisation des types Avec ou sans TS, on crée et on consomme des types au quotidien, par exemple une variable `asset` sous-entend la présence d'un certain nombre de propriétés sur cet objet. TypeScript n'introduit pas la notion de types, **il les explicite**, il peut donc vérifier automatiquement leur utilisation. Comme JS permet de créer des objets très facilement sans avoir besoin de définir leur schéma, il est plus difficile de maintenir des formats de données cohérents dans toute l'application. Expliciter ces types nous inciterait plus à réutiliser d'autres schémas de données existants, et nous permettrait ainsi d'avoir des formats de données plus homogènes. Mais nous ne faisons pas ça seulement pour faire plaisir à TypeScript, c'est aussi une aide précieuse **pour nous**. Il y aura moins besoin de regarder l'implémentation d'une fonction pour savoir comment s'en servir, moins besoin de regarder le schéma d'une collection pour savoir quels attributs il est possible d'accéder... l'auto-complétion nous le proposera immédiatement.     ## Inconvénients ### Maintenance des types On doit écrire des types, donc le développement d'une tâche peut-être rallongé. Mais comme on l'a vu pendant le BBL clean code, est-ce qu'on privilégie la rapidité d'écriture ou la maintenance dans le long terme ? Avec l'utilisation de TS, nous introduisons une complexité supplémentaire en utilisant un langage plus avancé que le JavaScript simple, mais nous sommes toutefois convaincus qu'en augmentant un peu la complexité du langage d'implémentation, nous pouvons réduire considérablement la complexité globale de la base de code. ### Duplication des déclarations de types En fonction de la stack technique dans l'application et des librairies utilisées, on risque de se retrouver à devoir définir plusieurs fois les types, notamment en ce qui concerne la base de données. Avec un setup basique avec Mongoose par exemple, il sera probable de devoir définir à la fois le schéma de la collection et la déclaration de type pour TypeScript. Bien sûr, avec un peu de travail, il semble possible de mutualiser ces définitions pour avoir une seule source de vérité. Par ailleurs, si on utilise GraphQL et Apollo, il semblerait qu'il y ait un très bon support TS et auquel cas cela nous faciliterait énormément le travail. ### Débogage au runtime La mise en place de TS (ou de n'importe quel transpileur) implique un débogage moins clair. En effet, le code JS qui est finalement exécuté est différent du code réellement écrit. Cela affectera notamment le débogage (par exemple dans le navigateur ou avec des breakpoints), mais aussi le monitoring (logs et Sentry). Ce problème pourra être résolu encore une fois avec un peu de travail en utilisant les source maps qui permettent de lier les fichiers transpilés à leurs sources. [node-source-map-support](https://github.com/evanw/node-source-map-support) semble être un outil très prometteur pour nous aider. ## Mise en place possible Il est totalement possible d'adopter petit à petit TypeScript. Nous pensons qu'il serait le plus utile dans les fonctions métier, celles qui calculent les soldes de comptes, ou encore dans le calcul des amortissements. Dans les faits, l'inférence de types de TS marche très bien, à tel point que dans la majorité des cas donner une signature exhaustive aux fonctions peut être suffisant (paramètres et types de retour). On peut rappeler que la mise en place de TS est **sans risque** pour nos utilisateurs : 0 dépendances au runtime, TS n'est **qu'un outil de dev**. TypeScript n'est que du JavaScript avec plus de features. Deux modes d'adoption semblent possibles : **Adopter TS tôt dans le cadre de la refonte** Le moment semble idéal pour commencer à utiliser TS. Les modules réécrits pourront bénéficier d'un typage dès le début, ce qui pourrait aussi faciliter le travail. **Adopter incrémentalement TS dans une base de code existante** Au contraire, il est également possible d'ajouter TypeScript sur un code existant. Pour cela, on pourra s'armer de _code mods_ (comme Airbnb l'a fait) pour automatiser autant que possible l'ajout de types dans le code. On pourra tout à fait faire cohabiter des fichiers JS et TS, typés ou non au sein de la même appli.   ## FAQ Cette partie rassemble l'ensemble des objections qu'on a pu avoir à l'utilisation de TS lors des différents échanges *café* :coffee:. L'objectif est d'y apporter une réponse pour pouvoir lancer des discussions sur les points qui peuvent être bloquants. ### :no_good: Je ne veux pas faire de Java / Angular / C# Nous non plus ! TypeScript nous laisse cette flexibilité de choisir jusqu'à quel point on veut utiliser les features du langage. C'est juste du JavaScript avec des features supplémentaires, libre à l'équipe de s'imposer des règles et des limites quand à son utilisation. TypeScript est très souvent lié dans les esprits à Angular ou Nest qui utilisent énormément les features avancées (comme les annotations pour faire de l'injection de dépendances). Mais il est tout à fait possible d'en faire un usage beaucoup plus simple tout en profitant de ses principaux avantages : productivité et sécurité. ### :pencil: Maintenir les types demandera trop de travail C'est vrai que ça demandera du travail, mais c'est nécessaire pour assurer la bonne cohérence du code et des formats de données dans toute l'application. En contrepartie de cet effort, les refactorings et la detection d'erreurs seront plus rapides. ### :bug: Ça ne va pas empêcher d'avoir des bugs Oui, c'est certain. L'utilisation de Typescript ne permet en aucun cas de faire disparaitre l'intégralité des bugs d'une application. En revanche, TS permet de detecter facilement des bugs, qui sont souvent assez simple, mais qui peuvent tout de même causé de gros problème dans l'intégrité des données de nos clients. C'est donc un gain de temps en correction/migrations des données. ### :mega: Pas besoin de TS si on nomme bien les fonctions et les variables C'est certain qu'il faut avoir de bons noms de variables, aussi explicites que possible. Mais un nom ne peut pas traduire à lui tout seul son format de données (ses propriétés et ses sous-types). Dans dans le cas d'une fonction, le nom de peut pas traduire l'ensemble de son contrat de manière exhaustive. Par ailleurs, l'intérêt de TypeScript réside dans le fait que l'on puisse vérifier de manière automatique que les formats de données ainsi que les contrats soient respectés. Même un excellent nommage demandera à ce qu'un humain relise le code pour vérifier qu'il soit correct sur ces aspects. ### :package: Il y a une étape de transpilation supplémentaire Oui, mais il est rare de devoir exécuter le compilateur TypeScript à la main pour faire les vérifications. Dans les faits, les IDE sont très bien intégrés avec TS et affichent les problèmes dès qu'ils sont écrits. Dans la CI, on peut espérer que cela prenne autant de temps qu'un linter. On pourrait en revanche rencontrer des difficultés à mettre en place TS si jamais on essayait de l'intégrer dans un framework tel que Meteor. ## :popcorn: :book: [Retour d'expérience de Airbnb sur leur migration de JS vers TS](https://www.youtube.com/watch?v=P-J9Eg7hJwE) [et aussi de Slack sur leur application PC](https://slack.engineering/typescript-at-slack-a81307fa288d)