Remplacer les commentaires par un meilleur code

Bonjour, je suis Valerio, ingénieur logiciel italien.

J'ai passé ces 10 dernières années à travailler en tant qu'ingénieur logiciel avec toutes sortes d'entreprises et de collègues.

Le développement logiciel est collaboratif par nature. Si vous travaillez pour une entreprise, quelle que soit sa taille, vous travaillez évidemment avec d'autres.

Je crois fermement aux commentaires en tant que documentation pour certaines fonctions ou classes entières car ils peuvent aider les développeurs de deux manières:

Naviguez dans le code en utilisant des commentaires pour diriger le comportement IDE;
Ajoutez plus d'informations contextuelles pour éviter tout malentendu sur la raison pour laquelle ce bloc de code a été conçu de cette façon (augmentation de la performance, résolution de bogues, etc.)

Lorsque vous faites partie d'une équipe, les commentaires dans le code peuvent provoquer des discussions et des désaccords. Accordons-nous sur le concept de " commentaires dans le code ".

<?php

public function calc() 
 {
  // Add b to a 
  $c =  $this->a +  $this->b;

  // return the result of a + b 
  return  $c;
}

Cela peut être le résultat d'une réunion où il est recommandé à l'équipe d'ajouter des commentaires sur le code.

Répéter le code est le pire que vous puissiez faire, ajouter des commentaires qui décrivent ce que fait votre code alors qu'il serait beaucoup plus clair de lire le code lui-même signifie que vous perdez du temps et que d'autres développeurs passeront également du temps à enquêter, sauf documentation.

Les développeurs juniors s'appuient sur les commentaires pour raconter des histoires quand ils doivent s'appuyer sur du code pour écrire leurs histoires. Les développeurs moins expérimentés ont tendance à utiliser des commentaires pour décrire l'histoire derrière un bloc de code.

On peut même être plus expressif en prenant soin des noms de classes, fonctions et variables sans écrire de ligne de commentaires.

Si vous ressentez le besoin d'écrire des commentaires pour expliquer à quoi sert votre fonction, la première chose que vous devez faire est d'envisager la possibilité de restructurer le code que vous avez écrit pour lui faire expliquer son objectif lui-même. Jetez un œil à l'exemple ci-dessous:

<?php

/**
 * Calculate spending limit by customer income and try to find a room to a lower price.
 */
public function rentRoom($income)
{
    $spending = round(($income*0.15) / 12);
    foreach ($this->rooms as $room) {
        if ($room->price <= $spending) {
            return $room;
        }
    }
    throw new RoomNotFoundException();
}

Une seule ligne de commentaire pourrait être acceptable. Ou pourrions-nous revoir le code pour le rendre plus clair, modulaire et éviter tout commentaire?

<?php

/**
 * Rent a room based on customer's income
 * 
 * @params integer $income
 */
public function rentRoom($income)
{
    try {
        $this->findRoomByPriceLimit(
            $this->calculateCustomerSpending($income)
        );
    } catch (\Eception $exception) {
        // do something with error
    }
}


public function findRoomByPriceLimit($limit) 
{
    foreach ($this->rooms as $room) {
        if ($room->price <= $limit) {
            return $room;
        }
    }
    throw new RoomNotFoundException();
}


public function calculateCustomerSpending($income, $percentage = 15)
{
    return round(
        ($income*($percentage/100)) / 12
    );
}

Le code est plus verbeux et il n'y a pas besoin de commentaires.

Les numéros ont maintenant une étiquette et les fonctions ont un nom qui explique clairement ce qu'elles font. Cet exemple peut sembler un peu excessif s'il est pris individuellement. Ce sur quoi vous devez concentrer votre attention est la stratégie, la valeur d'expliquer comment et pourquoi ce code s'y trouve en utilisant le code lui-même.

Mon conseil est de ne pas sous-estimer cet aspect. S'il y a trop de commentaires dans le code, le risque que vous et les autres développeurs accordiez moins d'attention à leur présence augmente de façon exponentielle, propageant également dans la documentation des informations anciennes et erronées.

Conclusion

Très souvent, des commentaires sont évidemment nécessaires pour expliquer des scénarios plus complexes ou des liens vers des bogues et il n'est pas possible de le faire en utilisant uniquement les noms dans le code.

Dans l'IDE moderne (comme PHPStorm ou VSCode), les commentaires sont souvent utiles pour améliorer la navigation dans le code.

Dans tous les cas, la prochaine fois que vous ressentez le besoin d'écrire des commentaires, vous pouvez vous demander s'il est possible d'avoir la même lisibilité en utilisant le code lui-même améliorant la maintenabilité de votre base de code.

J'espère que cet article pourra vous aider à gérer vos commentaires avec plus de confiance. Si vous voulez en savoir plus sur nous, visitez notre site Web à https://www.inspector.dev - Un tableau de bord de surveillance en temps réel complet en moins d'une minute.

Nous publions des articles sur notre expérience dans la création d'un produit pour un public mondial.