Nombre magique

Un nombre magique est une valeur, le plus souvent un integer, possédant un sens métier et présent en dur dans votre code.

public function setOrder(Order $order)
{
    if ($order->state === 2) {
        throw new Exception();
    }

    $this->order = $order;
}

À quoi correspond la valeur 2 ? Pourquoi cette valeur doit lever une exception ?

La comprehension d’un nombre magique n’est pas instinctive, elle nécessite des connaissances particulières ou un effort supplémentaire pour en saisir le sens.

Cette incertitude est délétère pour la lisibilité et la simplicité de votre code.

La démultiplication d’un même nombre magique au sein d’une application est également problématique pour sa maintenabilité.

Le moindre changement de valeur se devra d’être répercuté sur l’intégralité de l’application, c’est un travail qui peut s’avérer fastidieux et source d’erreurs.

Un nombre magique aura donc tendance à rendre votre code plus cryptique et moins maintenable sur le long terme ou pour un nouveau développeur intégrant le projet.

How to fix

Pour mitiger cette problématique nous allons chercher à encapsuler et expliciter le nombre magique.

Si ce nombre est statique qu’importe le contexte d’utilisation alors l’écriture d’une class de constantes peut s’avérer judicieux.

Par la même occasion ce nombre est désormais nommé, rendant notre situation bien plus explicite.

public function setOrder(Order $order)
{
    if ($order->state === OrderStateConstants::BLOCKED) {
        throw new UnexpectedStateException();
    }

    $this->order = $order;
}

Dans le cas contraire, si ce nombre est dynamique, il sera alors préférable d’utiliser un fichier de configurations.

public function setOrder(Order $order)
{
    if ($order->state === Config::get('orders.states.blocked')) {
        throw new UnexpectedStateException();
    }

    $this->order = $order;
}