Skip to main content

De la bonne utilisation des commentaires dans le code

> Il est important de commenter le code produit QUAND CELA EST VRAIMENT NECESSAIRE.

> Un code bien documenté est un code avant tout lisible par n'importe quel développeur, le plus exempt de commentaires possible.

> Les commentaires doivent décrire "pourquoi" le code est rédigé de cette façon au lieu du "comment" ou du "quoi".

Si le code est si compliqué qu'il nécessite beaucoup de commentaires, c'est peut-être qu'il y du travail d'amélioration à faire sur celui-ci.

❌ Exemple de commentaire totalement inutile​

Le genre que les IA aieme bien générer absolument partout.

public async Task CreateProductAsync(Product product, CancellationToken token)
{
    // Checks that the product is null.
    if (product is null)
    {
        throw new ArgumentNullException(nameof(product));
    }

    // Adds the product to the DbContext.
    await _context.Products.AddAsync(product);

    // Saves the changes.
    await _context.SaveChangesAsync(token);
}

Les commentaires ci-dessus n'apportent rien de plus que ce qu'indique déjà le code. Le développeur prendra plus de temps à lire le code et à le comprendre. Un dévelopeur sait lire du code comme un lecteur un roman.

✅ Exemple de commentaire utile​

private readonly Dictionary<IService, object> _resolvedServices = new Dictionary<IService, object>();
...

public void Dispose()
{
    // Code removed for brevity.

    // PERF: We've enumerating the dictionary so that we don't allocate to enumerate.
    // .Values allocates a KeyCollection on the heap, enumerating the dictionary allocates a struct enumerator.
    foreach (var entry in _resolvedServices)
    {
        (entry.Value as IDisposable)?.Dispose();
    }

    _resolvedServices.Clear();
}

Les commentaires ci-dessus sont très utiles, ils apportent des précisions sur "pourquoi" le dictionnaire est énuméré de cette façon. Dans ce cas précis, c'est plus performant et moins demandeur en ressources.

Droits d'auteur

Les commentaires mettant en évidence les droits d'auteur doivent suivre ce modèle :

✅ Faire​

    // ---------------------------------------------------------------
    // Copyright (c) Coalition of the Good-Hearted Engineers
    // FREE TO USE TO CONNECT THE WORLD
    // ---------------------------------------------------------------

❌ Ne pas faire​

    //----------------------------------------------------------------
    // <copyright file="StudentService.cs" company="OpenSource">
    //      Copyright (C) Coalition of the Good-Hearted Engineers
    // </copyright>
    //----------------------------------------------------------------

❌ Aussi, ne pas faire​

   /*
    * ==============================================================
    * Copyright (c) Coalition of the Good-Hearted Engineers
    * FREE TO USE TO CONNECT THE WORLD
    * ==============================================================
    */