Les meilleures API paraissent évidentes après coup. Vous appelez une méthode, elle accomplit l'unique chose que son nom promet, et elle continue de se comporter ainsi à travers une douzaine de versions. Cette fiabilité n'est pas le fruit du hasard. Elle résulte d'une poignée de décisions prises tôt et défendues dans la durée.

## Nommez les choses pour l'appelant, pas pour l'implémentation

Une API est une promesse écrite dans des noms de méthodes. Lorsque vous nommez une fonction selon son fonctionnement interne, chaque refactorisation menace de rompre cette promesse. Nommez-la selon ce que veut l'appelant, et l'implémentation reste libre de changer en dessous.

Le test est simple : lisez le site d'appel à voix haute. Si un nouveau coéquipier peut deviner ce qui se passe sans ouvrir le code source, le nom fait son travail.

## Rendez le cas courant sans effort

La plupart des appelants veulent la même chose la plupart du temps. Concevez le chemin par défaut pour qu'il ne nécessite aucune configuration, puis superposez des options pour les cas rares. Une API qui exige cinq paramètres pour une tâche de routine sera enveloppée dans une fonction d'assistance par la première équipe qui l'utilise, et vous maintenez désormais deux interfaces au lieu d'une.

> Chaque argument obligatoire est une petite taxe que vous prélevez sur chaque appel. Ne la prélevez que lorsque la valeur ne peut réellement pas être déduite.

## Versionnez le contrat, pas le code

Les changements incompatibles ne sont pas l'ennemi. C'est la surprise qui l'est. Lorsque vous devez casser quelque chose, donnez-lui un nouveau nom ou une nouvelle version et laissez l'ancien chemin fonctionner pendant une fenêtre de dépréciation claire. Les appelants pardonneront une migration qu'ils peuvent anticiper. Ils ne pardonneront pas un changement silencieux qui casse la production un mardi.

Une API qui vieillit bien est une API à laquelle vous pouvez cesser de penser. Construisez-la de sorte que les personnes qui en dépendent le puissent aussi.

Concevoir des API qui vieillissent bien

Personne ne planifie de réunion sur les temps de compilation. Ils grimpent une dépendance à la fois jusqu'à ce qu'une reconstruction complète soit assez longue pour justifier un coup d'œil à votre téléphone. Cette pause semble anodine. Elle ne l'est pas.

## Le contexte est ce que vous perdez réellement

Quand une compilation prend trente secondes, vous restez dans le problème. Quand elle en prend trois minutes, vous en sortez. Vous changez d'onglet, lisez un message, suivez un lien, et le temps que la compilation se termine, vous devez reconstruire le modèle mental que vous venez d'abandonner. Le coût en temps réel est de quelques minutes. Le vrai coût, c'est le rechargement.

## Les compilations lentes changent les comportements

Les équipes s'adaptent à un retour lent de manières qui rendent le code pire. Elles regroupent des changements non testés parce qu'exécuter la boucle coûte cher. Elles renoncent à la petite refactorisation parce qu'elle ne vaut pas une nouvelle attente. Elles cessent d'écrire l'expérience rapide qui aurait répondu à une question dans le code plutôt que dans un débat.

> La vitesse de votre boucle de rétroaction détermine la taille du plus petit changement que quiconque est prêt à faire.

## Traitez-le comme une métrique de premier plan

Mesurez le temps de compilation et de test comme vous mesurez la disponibilité. Mettez-le sur un tableau de bord. Fixez un budget et défendez-le en revue. Quand un changement pousse la compilation au-delà du budget, c'est un coût réel à peser, pas une erreur d'arrondi à ignorer.

Des compilations rapides ne sont pas un luxe réservé aux grandes équipes. Elles sont le socle qui permet à une petite équipe de continuer à avancer comme une petite équipe.

Le vrai coût d'une compilation lente

Demandez à un ingénieur comment il s'améliore et il vous parlera d'écrire plus de code, de monter des projets personnels, d'apprendre un nouveau langage. Presque personne ne dit pratiquer la lecture. Pourtant, dans toute vraie équipe, lire est le métier. Vous lisez pour relire, pour déboguer, pour comprendre ce que vous êtes sur le point de modifier.

## Commencez par la forme avant les détails

Quand vous ouvrez un fichier inconnu, résistez à l'envie de lire de haut en bas. Survolez d'abord la structure. Quels sont les principaux exports ? Où entrent les données et où sortent-elles ? Une carte rapide de la forme fait que les détails trouvent une place au lieu de s'entasser.

## Suivez un seul chemin jusqu'au bout

Choisissez un scénario réaliste unique et retracez-le d'un bout à l'autre. Une requête, un clic, une entrée. Suivre un chemin concret vous apprend davantage que lire chaque branche, car cela montre ce qui se passe réellement plutôt que tout ce qui pourrait se passer.

> Vous ne comprenez pas un système tant que vous ne pouvez pas prédire ce qu'il fera avec une entrée que vous n'avez jamais vue.

## Lisez à dessein du code que vous admirez

Réservez du temps pour lire une bibliothèque bien construite comme vous étudieriez un bon texte. Remarquez comment elle nomme les choses, où elle trace ses frontières, ce qu'elle a choisi de ne pas faire. Vous absorberez des modèles que vous pourrez mobiliser plus tard sans avoir à les réinventer sous pression.

La lecture n'est pas la part passive de l'ingénierie. C'est là que se produit l'essentiel de la compréhension. Accordez-lui la même pratique délibérée que vous accordez à tout le reste, et l'écriture devient elle aussi plus facile.

Ingénierie

Concevoir des API qui vieillissent bien

Le vrai coût d'une compilation lente

Lire du code est une compétence qui se travaille