La distance sémantique désigne l’écart qui peut exister entre le nom d’une méthode et les actions qu’elle réalise réellement. Une méthode bien nommée est une promesse explicite : elle annonce ce qu’elle s'apprête à faire et rien d’autre.
Le nom d'une méthode agit comme un contrat implicite entre celui qui écrit et celui qui lit. Rompre ce contrat, c’est introduire de l’ambiguïté. Le code surprend là où il devrait être prévisible : il devient source de couplage, d’incompréhension, et souvent de comportements inattendus.
Une bonne méthode ne devrait faire qu’une seule chose à la fois. Et cette chose devrait être anticipée à la seule lecture de son nom. Dans les faits, toutes les méthodes ne sont pas confrontées de la même manière à cette exigence car ces dernières ne se situent pas toutes au même niveau d’abstraction.
En amont de la chaîne d’appel, certaines méthodes jouent un rôle d’orchestration : elles composent, déclenchent, coordonnent. Leur nom exprime une intention générale et non une série d’actions détaillées. Une certaine distance sémantique y est acceptable tant que le comportement global reste cohérent avec l’intention exprimée : cette distance reflète alors un choix d’abstraction raisonné.
Mais plus on descend dans cette chaîne d’appel et plus on se rapproche du code qui exécute réellement les choses. Les méthodes de bas niveau n’orchestrent pas : elles appliquent. Elles manipulent des données, produisent des effets concrets. Leur périmètre est restreint et leur rôle précis, leur nom doit l’être tout autant et notre toléerance à la distance sémantique est faible.
À ce niveau, une distance sémantique même faible devient alors un problème, elle signale une confusion entre ce qui est promis et ce qui est accompli par la méthode.
Prenons un exemple pour illustrer ces notions, une méthode nommée requestHttpTokenValidation semble annoncer une tâche technique bien définie : celle de valider un token via HTTP.
function requestHttpTokenValidation(Validation $validation)
{
$valideable = DnsTxtTokenValidation::create([
'token' => $validation->token,
]);
Mail::to($validation->user)->send(new ValidationEmail($valideable));
return $valideable;
}
Mais à l’ouverture de la méthode, on découvre qu’elle envoie également un email ... ce comportement supplémentaire n’était pas attendu, le nom annonçait une seule action et le code en réalise deux.
Cette surprise n’est pas anodine : elle signale un couplage insidieux entre une logique d’authentification et une logique de notification. Deux responsabilités qui devraient être distinctes se retrouvent mêlées dans une même méthode, au mépris du principe de séparation des préoccupations.
À ce niveau dans la chaîne d'appels, cette double responsabilité est problématique, car en plus d'accentuer le couplage elle rend contraignante l'utilisation de la méthode : il n'est plus possible de valider sans envoyer un mail.
Pour corriger ça, il faut d’abord se demander : est-ce que ce comportement a réellement sa place ici ? Si oui, alors il faut alors le rendre explicite — via une séparation claire, un événement, un dispatcher, ou simplement un nom plus honnête. Si non, il faut l’extraire, le déplacer, le repenser plus en amont de la chaine d'appels.
La distance sémantique n’est donc pas qu’un problème de lisibilité. Elle révèle souvent un défaut plus profond : un mauvais découpage des responsabilités. Et plus elle se manifeste bas dans la hiérarchie d’appel, plus ses conséquences sont critiques.
Lorsque vous nommez une méthode, lisez son nom à voix haute, puis demandez vous sans en consulter le contenu : "Est-ce que ce que je m’apprête à lire va confirmer cette promesse ou la trahir ?" Si vous hésitez, c’est qu’il y a sans doute une distance à réduire.