Les commentaires ont leur place dans le code, mais ils ne doivent pas servir de béquille pour pallier un code mal conçu ou difficile à comprendre. Un code bien écrit doit être suffisamment explicite pour se passer de commentaires inutiles. Un code smell fréquent dans les codes legacy est la surabondance de commentaires qui tentent d'expliquer des parties du code mal nommées ou complexes.

Dans ce chapitre, nous allons aborder les problèmes liés à l'utilisation excessive de commentaires et l'importance de bien nommer son code pour le rendre plus lisible et maintenable.

TLDR;

Pour améliorer la lisibilité et la maintenabilité du code, évitez les commentaires inutiles et privilégiez un nommage clair et explicite pour les méthodes et les variables. Un code bien écrit se suffit à lui-même et n'a pas besoin de commentaires superflus.

Pourquoi les commentaires inutiles sont problématiques

1. Ils peuvent rendre le code moins lisible en ajoutant du bruit visuel.

2. Ils nécessitent un entretien supplémentaire lors des mises à jour du code, ce qui peut entraîner des incohérences si les commentaires ne sont pas maintenus à jour en parallèle.

3. Ils peuvent masquer les vrais problèmes de conception qui devraient être résolus plutôt que d'être expliqués par un commentaire.

Comment éviter les commentaires inutiles

1. Donnez des noms explicites à vos variables, fonctions et classes. Un nom bien choisi peut souvent remplacer un commentaire en décrivant clairement l'intention et le fonctionnement de l'élément de code.

2. Décomposez les fonctions et les classes trop complexes. Si vous avez besoin d'expliquer comment fonctionne une partie du code avec un commentaire, c'est peut-être le signe qu'il est temps de la refactorer en plusieurs éléments plus simples et compréhensibles.

3. Utilisez des commentaires uniquement pour expliquer des éléments non évidents ou des décisions de conception spécifiques. Les commentaires doivent apporter une valeur ajoutée à la compréhension du code, et non simplement paraphraser ce qu'il fait.

En privilégiant un code bien nommé et en évitant les commentaires inutiles, vous contribuerez à rendre votre code legacy plus lisible, compréhensible et maintenable. Ce faisant, vous réduirez également la probabilité que d'autres développeurs introduisent des erreurs ou des régressions en travaillant sur le code.

Pour illustrer les points abordés dans ce chapitre, voici quelques exemples de code C# montrant des commentaires inutiles et leur version refactorée.

Exemple

Code à ne pas faire :

// Class to manage employees and their salaries
public class BadClass
{
    double s; // salary
    double d; // deductions
    double n; // net salary

    // Constructor
    public BadClass()
    {
    }

    // DSC - 2021-12-31 : Calculate the net salary
    // MSC - 2022-01-13 : Update the net salary calculation
    // Calculate the net salary from an input salary and the deduction rate
    public double Calc(double salary, double rate)
    {
        // Initialize the gross salary
        s = salary;

        // Calculate the deductions
        d = s * rate;

        // Bonus = salary * (1 - deductionRate) * 0.05
        // 0.05 is the applied bonus rate
        double b = s * (1 - deductionRate) * 0.05;

////////////////////////////// IMPORTANT PART
        // Calculate the net salary
        n = s - d + b;
////////////////////////////// END OF IMPORTANT PART

        /*
        if (d > 0,5)
        {
            d = 0,5;
        }
        else
        {
            d = d;
        }

        n = s - d;
        */

        // Display the net salary
        Console.WriteLine("Net salary: " + n);
    }
}

Ce code apparemment court présente de nombreux problèmes. Décortiquons ce code pour mieux comprendre ce qui ne va pas.

// Class to manage employees and their salaries
public class BadClass

Ici, on retrouve un commentaire au-dessus de la classe pour compenser le nom peu explicite de cette dernière.

double s; // salary
double d; // deductions
double n; // net salary

Ici, on retrouve des variables mal nommées et qui, visiblement, n'ont pas besoin d'être déclarées à ce niveau de la classe.

// DSC - 2021-12-31 : Calculate the net salary
// MSC - 2022-01-13 : Update the net salary calculation
// Calculate the net salary from an input salary and the deduction rate
public void Calc(double salary, double rate)

On pourrait penser que cette pratique relève de la pure fiction pour alimenter un blog, mais en réalité, j'ai déjà rencontré ce type de commentaires bien trop souvent en parcourant du code. Quel est le problème ici ? Les commentaires de ces deux développeurs auraient peut-être eu du sens à une époque où les gestionnaires de code source n'étaient pas courants. Cependant, à l'heure actuelle, ils n'ont plus aucune raison d'exister. Si vous rencontrez de tels commentaires dans le code, n'hésitez pas à les supprimer définitivement. L'historique de votre gestionnaire de code source vous permettra de retrouver l'auteur du commit.

De même pour la méthode Calc qui nous dit, à travers son commentaire, qu'elle calcule un salaire net, mais en réalité, elle se contente de l'afficher dans la console. Ici, la méthode a sûrement évolué avec le temps, mais le commentaire n'a pas été mis à jour par les développeurs successifs.

        /*
        if (d > 0,5)
        {
            d = 0,5;
        }
        else
        {
            d = d;
        }

        n = s - d;
        */

Il est important de mentionner également le problème du code mort commenté. Ce code nous induit en erreur sur sa réelle utilité et son intention. Est-ce du code désactivé de manière temporaire ? S'agit-il d'un test d'un développeur ? Cela nuit globalement à la lisibilité et à la compréhension du code plus qu'autre chose. Il convient donc de le supprimer purement et simplement. Les gestionnaires de code source que nous utilisons nous permettent déjà d'historiser nos changements et d'y revenir facilement au besoin.

Voici une version corrigée de ce code, en supprimant les commentaires inutiles et en nommant explicitement et clairement nos méthodes et nos variables :

Version corrigée :

public class SalaryCalculator
{
    private const double bonusRate = 0.05;

    public double PrintNetSalary(double salary, double rate)
    {
        var netSalary = CalculateNetSalary(salary, rate);

        Console.WriteLine("Net salary: " + netSalary);
    }

    private static double CalculateNetSalary(double salary, double rate)
    {
        var deductions = salary * rate;
        var bonus = salary * (1 - deductionRate) * bonusRate;

        return salary - deductions + bonus;
    }
}

Alors, qu'en pensez-vous ? On comprend mieux l'intention du code sans avoir la nécessité de garder les commentaires initiaux, n'est-ce pas ?

Conclusion

Pour conclure, il est essentiel d'être rigoureux dans l'écriture du code et d'apporter toute notre attention à la rédaction d'un code de qualité qui respecte les bonnes pratiques de développement et le Clean Code. Un code de qualité et bien structuré simplifie sa compréhension par nos pairs, mais également sa maintenance et son évolutivité. Un code bien écrit se suffit à lui-même.

Alors, la prochaine fois que vous vous apprêtez à ajouter un commentaire, posez-vous la question : est-ce vraiment nécessaire, ou puis-je simplement le rendre plus clair en nommant mieux mes variables et mes méthodes et en étant le plus explicite possible sur l'intention de mon code ?