Nombre magique

Un nombre magique est une valeur, le plus souvent un integer, possédant une signification métier et présente 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 devrait-elle déclencher une exception ?

La compréhension d'un nombre magique n'est pas instinctive, elle requiert des connaissances particulières ou un effort supplémentaire pour en saisir le sens.

Cette incertitude nuit à la lisibilité et à la simplicité de votre code.

La multiplication d'un même nombre magique au sein d'une application pose également des problèmes de maintenabilité.

Le moindre changement de valeur devra être répercuté sur l'ensemble de l'application, ce qui peut s'avérer fastidieux, couteux en temps et source d'erreurs.

En conséquence, l'utilisation de nombres magiques aura tendance à rendre votre code plus cryptique et moins maintenable sur le long terme, surtout pour un nouveau développeur intégrant le projet.

How to fix

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

Si ce nombre est statique, quel que soit le contexte d'utilisation, la création d'une classe Enum peut s'avérer judicieuse.

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 === OrderStateEnums::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;
}