La distance sémantique est définie par l'écart qui existe entre le nom d'une méthode et les actions qu'elle réalise.
Dans sa forme anglophone, le principe est également connu sous le nom : "principle of least surprise".
function requestHttpTokenValidation(Validation $validation)
{
$valideable = DnsTxtTokenValidation::create([
'token' => $validation->token,
]);
Mail::to($validation->user)->send(new ValidationEmail($valideable));
return $valideable;
}
Rien n'indique depuis la signature de la méthode que la création d'une validation implique d'envoyer un mail : ce comportement n'est pas attendu.
La définition d'une méthode se doit d'être claire sur ses intentions, tout comportement caché est une source d'incompréhensions et de surprises que l'on doit éviter.
Une grande distance sémantique est souvent symptomatique d'un problème de conception et révélateur d'une classe possédant trop de préoccupations.
How to fix
Dans le cas présent, il est important de se poser la question suivante :
Cette préoccupation est-elle suffisamment proche pour exister au sein de cette méthode ?
Si la réponse est oui, on peut alors chercher à découpler cette méthode en utilisant, par exemple, un Event Dispatcher.
function requestHttpTokenValidation(Validation $validation)
{
$valideable = DnsTxtTokenValidation::create([
'token' => $validation->token,
]);
Event::dispatch(new ValidationRequested($valideable));
return $valideable;
}
Au contraire, si la réponse est non, nous sommes alors probablement face à un couplage temporel, Il sera conseillé de refactoriser en profondeur cette méthode pour en extraire les différentes préoccupations.
Une histoire de composant
Il convient également d'apprécier la nature du composant contenant la méthode pour déterminer si oui ou non elle génère une distance sémantique problématique à la compréhension du code.
Par exemple, un contrôleur se trouve généralement dans une strate élevée de votre application, au plus proche de vos utilisateurs, et représente un cas d'utilisation. Il est évident que le nom d'une méthode de contrôleur aura difficilement la capacité de refléter toutes ses intentions.
Au contraire, une classe action ou service répond à un besoin beaucoup plus précis et dogmatique et se trouve dans des strates beaucoup plus basse de votre application. Il sera nécessaire de porter une attention particulière à la distance sémantique de ces classes.
En s'enfonçant dans votre application, les noms de vos méthodes doivent être long, car ces méthodes, au sein de strates basses, représentent des détails d'implémentation.