Nommer, c'est chercher le bon mot au Scrabble
En programmation, nommer les choses, c'est comme chercher le bon mot dans une partie de Scrabble. Les lettres sont limitées, le plateau est encombré, et le mot doit s'accorder avec tout ce qui est déjà posé.
Pourquoi un nom est-il plus difficile qu'il n'y paraît ?
Un nom doit dire ce qu'est une chose, ce qu'elle fait et ce qu'elle n'est pas, en un ou deux mots. C'est peu de place pour beaucoup de sens. Une variable appelée data ne dit rien. Une fonction appelée process en dit encore moins.
Le nom est aussi lu bien plus souvent qu'il n'est écrit. Il est écrit une fois, à la création du code. Ensuite, chaque développeur qui ouvre le fichier le lit, et chaque appel le répète. Un nom un peu faux coûte un peu à chaque fois, et ce coût est payé par chaque lecteur qui suit.
C'est pour cela que le nommage mérite un effort. L'effort est petit comparé au nombre de fois où le nom sera lu.
Un nom est aussi la première documentation que rencontre un lecteur. Avant d'ouvrir le corps de la fonction, il voit son nom dans l'appel. Si le nom est précis, il continue de lire sans s'arrêter. S'il est vague, il doit ouvrir le corps pour savoir ce que fait l'appel, et la lecture ralentit partout où le nom apparaît.
Pourquoi les commentaires perdent-ils la bataille du nommage ?
Commenter, c'est la solution de facilité. Cela vous permet de blablater encore et encore, sans faire le vrai effort de résumer les choses en un ou deux mots. Ce n'est pas facile, croyez-moi !
Commenter est aussi un mauvais trade-off, parce qu'un commentaire devient obsolète très vite. La raison est mécanique. Un commentaire est une deuxième copie de la vérité, stockée en prose. Le compilateur ne le lit pas, les tests ne l'exécutent pas, et un refactoring ne le met pas à jour. Quand le code change, le commentaire reste où il était, et les deux copies s'éloignent l'une de l'autre.
Un nom ne dérive pas de la même façon. Il fait partie du code : le compilateur le vérifie, et les outils de renommage mettent à jour tous les appels d'un coup. C'est cela, être « refactor-proof ». Le commentaire ne l'est pas. Il ne survit que jusqu'au prochain changement.
Martin Fowler dit la même chose dans Refactoring. Quand un commentaire explique un code pas clair, changez d'abord le code, pour que l'explication ne soit plus nécessaire.
Qu'est-ce qui fait un bon nom ?
Je pratique l'art de « trouver de bons noms » depuis des années et je ne suis toujours pas parfait. Mais j'ai beaucoup appris en chemin.
Phil Karlton a résumé la difficulté en une ligne : « There are only two hard things in Computer Science: cache invalidation and naming things. » L'invalidation de cache est difficile parce que le système doit savoir quand une vieille donnée cesse d'être vraie. Nommer est difficile pour une raison proche. Le nom doit rester vrai pendant que le sens de la chose évolue.
Kent Beck appelle cet objectif un « intention-revealing name » dans Smalltalk Best Practice Patterns. Le nom doit dire au lecteur pourquoi la chose existe, pas comment elle est construite. Un nom qui révèle l'intention survit à un changement d'implémentation. Un nom qui décrit les étapes, non.
Nommer est aussi un test de votre compréhension. Si vous n'arrivez pas à nommer une chose en quelques mots, le design n'est sans doute pas encore clair. La difficulté est une information utile.
Un bon nom réduit aussi les choix du prochain développeur. Quand une fonction s'appelle send_invoice_reminder, personne ne se demande si elle doit aussi débiter le client. Quand elle s'appelle handle, chaque lecteur se demande ce qu'elle fait d'autre, et le code autour grossit dans la mauvaise direction.
Comment trouver un bon nom ?
- Dites à quoi sert la chose, en une phrase. Utilisez les mots de cette phrase comme nom.
- Utilisez les mots du domaine. Un paiement a un montant, pas un nombre.
- Nommez le résultat ou l'intention, pas les étapes pour y arriver.
- Lisez l'appel à voix haute, avec les mots de l'appelant.
- Si le nom a besoin d'un « et », coupez la chose en deux.
- Renommez dès que le sens change, pas des semaines plus tard.
- Utilisez la fonction de renommage de l'IDE, avec les tests qui tournent, pour que tous les appels bougent ensemble.
L'étape 6 est celle que la plupart des équipes sautent. Un nom qui était juste le mois dernier peut être faux après une seule nouvelle feature. Renommer maintenant coûte peu. Un nom trompeur qui survit un an coûte bien plus cher.
Quand un commentaire a-t-il encore sa place dans le code ?
Tous les commentaires ne sont pas du gaspillage. John Ousterhout, dans A Philosophy of Software Design, défend l'idée que les commentaires qui décrivent une abstraction portent une information que le code ne peut pas exprimer. Ils disent à quoi sert l'abstraction, ce qu'elle garantit, et de quelles hypothèses elle dépend. Ces faits ne se voient pas dans la signature d'une fonction.
La règle a donc une limite. Un commentaire qui répète ce que fait la ligne suivante est du gaspillage, et il doit être remplacé par un meilleur nom. Un commentaire qui explique pourquoi une décision a été prise, ou ce qu'un appelant doit savoir, mérite sa place. Il n'est pas en concurrence avec le nom. Il dit ce que le nom ne peut pas dire.
Le trade-off est clair. Les noms portent le « quoi », et les garder vrais ne coûte rien. Les commentaires ne valent leur coût que pour le « pourquoi » et le contrat, parce qu'il faut les maintenir à la main. Quand vous vous surprenez à écrire un commentaire pour expliquer un nom, c'est le nom qu'il faut corriger.
💡 Si vous avez besoin d'un commentaire, c'est que vous n'avez pas mis assez d'effort dans le nommage.
Ressources et bibliographie
- Phil Karlton, via Martin Fowler, TwoHardThings (martinfowler.com, 2009). https://martinfowler.com/bliki/TwoHardThings.html
- Kent Beck, Smalltalk Best Practice Patterns, intention-revealing names (Prentice Hall, 1996). https://www.oreilly.com/library/view/smalltalk-best-practice/9780132852098/
- John Ousterhout, A Philosophy of Software Design (Yaknyam Press, 2018). https://web.stanford.edu/~ouster/cgi-bin/aposd.php
- Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship (Prentice Hall, 2008). https://www.oreilly.com/library/view/clean-code-a/9780136083238/
- Martin Fowler, Refactoring: Improving the Design of Existing Code, 2nd edition (Addison-Wesley, 2018). https://martinfowler.com/books/refactoring.html
Publié d'abord sur LinkedIn : le post d'origine
