Nommer une fonction ou une classe peut se faire dans deux sens : de l'intérieur vers l'extérieur, ou de l'extérieur vers l'intérieur. Ce choix décide de la lisibilité du code pour l'appelant. Il décide aussi si le nom survivra au prochain refactoring.

À quoi ressemble un nom construit de l'intérieur ?

Nommer de l'intérieur, c'est regarder ce que fait le code de la fonction ou de la classe, puis essayer de mettre un nom dessus. On résume les instructions et on les colle bout à bout. C'est nul.

Voici l'exemple. C'est une méthode publique d'une classe Display, nommée de l'intérieur.

Une méthode publique nommée DisplayIfReadyAndUpdateLastDisplayed, qui vérifie le statut, écrit le message et lève une exception quand l'écran n'est pas prêt

Lisez le nom, puis lisez le corps. Le nom liste chaque condition et chaque action : la vérification que l'écran est prêt, l'écriture, la mise à jour du dernier message, l'exception. On dirait un changelog de l'implémentation, pas une description de l'intention.

Pourquoi un nom construit de l'intérieur pénalise-t-il l'appelant ?

Un nom dit à l'appelant à quoi s'attendre. Quand le nom décrit les étapes, l'appelant doit garder ces étapes en tête. C'est le premier coût.

Cette fonction n'exprime pas l'intention de l'appelant. Au contraire, elle rend le code client moins lisible : elle glisse des détails inutiles dans le code d'orchestration. L'appelant voulait afficher un message. Le voilà qui lit des histoires d'écran prêt, de mises à jour et d'exceptions, alors qu'aucun de ces détails ne le concerne.

Le deuxième coût arrive plus tard. Un nom construit à partir du corps doit changer chaque fois que le corps change. Déplacez la vérification ailleurs, et le nom est faux. Soit on réécrit le nom, et il faut repasser sur tous les points d'appel. Soit on le laisse tel quel, et c'est pire : un nom faux trompe chaque lecteur qui lui fait confiance.

David Parnas défendait une idée proche en 1972. Les modules doivent être découpés autour des décisions de design qui risquent de changer, et chaque module doit cacher ces décisions derrière son interface. Un nom construit de l'intérieur expose exactement les décisions que l'appelant ne devrait pas voir.

À quoi ressemble un nom construit de l'extérieur ?

Voici l'alternative. Display.write(message) est plus expressif. Il ne contient aucun détail d'implémentation, et il résistera mieux aux futurs refactorings du code de la fonction.

Le nom énonce l'intention du point de vue de l'appelant. L'appelant veut écrire un message sur l'écran, et le nom dit exactement cela. Le corps peut changer. Il peut vérifier que l'écran est prêt, mettre le message en tampon ou réessayer plus tard : le nom reste vrai. L'appelant n'a pas besoin de savoir lequel de ces cas se produit.

Nommer les fonctions de l'extérieur peut rendre le code plus lisible. Le nom donne une idée de ce que la fonction est censée faire, quelle que soit la façon dont elle est implémentée.

Robert C. Martin défend la même idée dans Clean Code, au chapitre sur les noms qui ont du sens. Le nom doit dire à quoi sert la chose. Kent Beck appelle cela un nom qui révèle l'intention. C'est la même idée, avec un autre vocabulaire.

Comment nommer de l'extérieur ?

  1. Écrivez d'abord l'appel, comme l'appelant l'écrira.
  2. Nommez la méthode d'après l'intention de l'appelant.
  3. Cachez les vérifications et l'ordre des opérations dans la méthode.
  4. Demandez-vous si le nom serait encore vrai si le corps était réécrit demain.
  5. Déplacez les étapes d'implémentation dans des helpers privés, nommés d'après leur propre travail.
  6. Faites relire le nom par un collègue qui n'a pas écrit le code.

L'étape 1 est l'habitude qui compte le plus. Écrire l'appel en premier oblige l'appelant à définir le contrat avant que le corps existe. C'est la même discipline qu'écrire le test en premier, et l'effet est le même : le design est jugé de l'extérieur.

Quand un renommage s'impose, faites-le avec soin. Dans Refactoring, Martin Fowler traite le changement de nom d'une fonction comme un refactoring de base. Il est sûr quand des tests couvrent le comportement. Il ne coûte presque rien quand il est fait tôt.

Quand peut-on nommer de l'intérieur ?

Un nom construit de l'extérieur fait une promesse, et cette promesse doit être honnête. Si le nom dit write, mais que la méthode jette le message en silence quand l'écran n'est pas prêt, le nom est un mensonge. Un mensonge est pire qu'un nom construit de l'intérieur. Lui, au moins, dit la vérité sur le corps.

Le contrat doit donc être visible. Le nom n'a pas à lister toutes les conditions. Mais l'appelant doit quand même apprendre que la méthode lève une exception quand l'écran n'est pas prêt : par l'exception, par le type ou par la documentation. John Ousterhout décrit l'idéal comme un module profond : une interface simple devant un comportement conséquent. L'appelant voit l'interface simple, et la complexité reste derrière. Le contrat fait partie de cette interface.

Les helpers privés sont l'autre cas. Un helper qui n'a qu'un appelant, dans la même classe, n'est pas une interface que quelqu'un lira de l'extérieur. Le nommer de l'intérieur est acceptable, parce que personne d'autre ne dépend de son nom. La règle du nommage de l'extérieur s'applique aux noms que d'autres morceaux de code appelleront.

Le trade-off est clair. Un nom construit de l'extérieur demande plus de réflexion avant que le code existe, et il rembourse à chaque lecture. Un nom construit de l'intérieur s'écrit vite, et chaque lecteur le paie plus tard.

💡 Nommez la fonction pour l'appelant, et laissez l'implémentation se cacher derrière le nom.

Ressources et bibliographie

Publié d'abord sur LinkedIn : le post d'origine