Écrire des commentaires de code PARFAITS : le guide ultime.

Imaginez. Vous avez pris 2 semaines de vacances, loin de votre travail, loin de vos projets, loin du code. Actuellement, vous êtes en train de prendre votre meilleur bain de soleil au bord d’une plage de méditerranée, mocktail à la main et Satie dans les oreilles.

Vous êtes loin d’imaginer que votre rentrée va être un cauchemar.

Et oui, tout bon développeur sait ce que ça fait de mettre un projet de côté pour le reprendre plus tard. On se dit qu’on va pouvoir se remettre dans le bain en 30 secondes, comme si on avait fait snapshot, et péter la forme après le premier café.

Alors qu’en réalité, un jour de rentrer, vous allez passer la plupart de votre temps à vous gratter la tête, à essayer de vous rappeler ou vous en étiez, et à déchiffrer votre code qui s’est transformé en hiéroglyphes pendant vos deux semaines de vacances.

La rentrée aurait été moins rude si vous aviez commenté votre code, mais déjà, pas tout le monde le fait, et surtout, très peu de personnes le font correctement.

Et j’ai beau parler, mais je suis exactement pareil.

/// <summary>
/// Fonction qui fait quelque chose mais je sais plus quoi.
/// </summary>
public static int Thing(int stuff, bool b);

Commenter du code, c’est chiant, on ne va pas se mentir là-dessus. Ça vient surtout du fait que quand on commente, on a l’impression de ne pas produire de valeur ajoutée, puisqu’on ne travaille “techniquement” pas sur le produit final.

Et bien souvent, on va se retrouver dans des situations où du code nous parait tellement évidant qu’on se dit que ça serait du temps perdu de le commenter.

Évidement, c’est paradoxal puisque la raison pour laquelle le code semble si simple, c’est parce qu’on l’a fait nous-même et que l’algorithme est encore tout frais dans notre tête.

Et c’est typiquement en revenant dessus 6 mois plus tard, après avoir dormis 180 nuits, que l’on comprend notre erreur monumentale.

Et si ça ne nous concernait que nous, ça “passerait”, mais ça s’aggrave quand on travaille en équipe. Tout ce temps précieux perdu à discuter du comportement des algorithmes avec vos collègues alors qu’une petite minute investie dans l’écriture d’un commentaire aurait suffi. C’est dommage.

Mais j’ai gardé le meilleur pour la fin, la situation dans laquelle personne ne souhaite se retrouver : reprendre un code fait par un ancien développeur qui n’a rien commenté ou documenté.

Je me suis personnellement retrouvé dans cette situation une paire de fois, et ça m’a fait perdre des JOURS ENTIERS de travail. Et je peux vous assurer que vous poser devant un programme et ne rien coder pendant une heure parce que vous n’avez aucune foutre idée de ce qui est en train de se passer, on est à la limite d’une méthode de torture chinoise.

…Excusez-moi, je me suis un peu emporté, mais c’est pour vous dire que commenter son code, c’est important. Et j’ai beau râler, mais au final, avoir un programme sans aucun commentaire du tout, c’est vraiment rare. On commente tous plus ou moins à un moment donné.

Mais là où c’est contre productif, c’est que la grande majorité des développeurs commentent en mode “post-it”, en mettant deux-trois lignes par-ci par-là pour expliquer du code un peu compliqué, en se disant qu’ils ont atteint leur quota de commentaire pour la journée.

// a prends la valeur de b
a = b;
// on retourne a
return a;

Ça peut servir pour se rafraîchir la mémoire de temps en temps, mais ce n’est pas ça qui va vous permettre de détailler le fonctionnement de votre programme, ni d’expliquer à vos (futurs) collègues ce que vous avez fait. C’est comme écrire une procédure sur un mouchoir en papier.

Le commentaire de code, c’est une discipline à part entière. Ça demande de la rigueur, des règles, un framework et des outils. Et ce sont ces quelques minutes investies à écrire des commentaires de qualité qui vont vous permettre de gagner des heures sur le long terme, et donc potentiellement des centaines (milliers ?) d’euros si vous avez un coût horaire.

Parler carrément de discipline pour des commentaires, ça parait overkill, mais je vous rassure, ça ne l’est pas. Je le rappel, le but est de gagner du temps et de la qualité de code, pas de jeter des heures par la fenêtre pour le plaisir.

Ainsi, grâce à ma solution, vous allez être en mesure de pouvoir élucider chaque mystère de votre code en ne laissant aucune zone blanche (et être aimé par vos collègues au passage), mais aussi de pouvoir écrire les meilleurs commentaires possibles en un minimum de temps.

Vous allez aussi découvrir des outils qui vont venir exploiter vos commentaires pour gagner encore plus en productivité, et qui iront même jusqu’à créer la documentation de votre application pour vous (si si !).

Intéressé ? Alors allons y.

2 types de commentaires

Avant de bien commenter, il faut d’abord comprendre pourquoi on commente et comment on le fait. Ça parait évident, mais il y a des subtilités qui ne sont pas claires chez tout le monde.

Vous n’êtes pas sans savoir qu’il existe 2 types de commentaire. Par là, je ne parle pas des commentaires en ligne (//) et du commentaire en bloc (/**/), ça, à la limite, on s’en fout un peu. Je vais plutôt me concentrer sur le contexte de ceux-ci.

Si vous ne les connaissez pas, les voici :

• Les commentaires de définition : ils servent à expliquer le rôle d’un membre (variable, fonction, propriété, méthode…), ce qu’il fait et ce qu’il représente.
• Les commentaires d’instruction : ils servent à expliquer le fonctionnement une instruction (une ligne de code) ou d’un bloc d’instructions (if, for…) en détail.

// Commentaire de définition
public Food Retrieve(string foodName) 
{
    // Commentaire d'instruction
    foreach (Food food in MyFood) 
    {
        if(food.Name == foodName) 
        {
            MyFood.Remove(food);
            return food;
        }
    }

    return null;
}

Vous ne voyez peut-être pas la différence dit comme ça, mais chaque type de commentaire à un rôle et un but différent, et donc sa propre manière d’être écrit.

Si vous voulez directement voir à quoi ça ressemble dans un vrai programme, je vous le montre concrètement dans mon bonus.

Commentaire de définition

Les commentaires de définition vont être attaché à la définition de vos membres. Ce sont eux qui vont venir détailler le fonctionnement de tout votre programme. Autrement dit, une personne extérieure doit être en mesure de comprendre l’intégralité du fonctionnement de votre application rien qu’en lisant ses commentaires de définition, même sans jeter un coup d’œil au code.

En programmation orientée objet, un programme n’est en général rien d’autre que des interactions entre des objets, donc si chacun des membres de vos classes est expliqué, alors vous pouvez affirmer votre projet est intégralement documenté.

Bon, dans la pratique, comment on fait ?

Dans l’idée : vous prenez tous vos membre un par un, et vous posez un commentaire au-dessus d’eux.

// Ajoute une liste d'aliments au frigot
public void Fill(List<Food> food) 
{
    MyFood.AddRange(food);
}

Ok, pourquoi pas, mais on peut faire beaucoup mieux en se faisant ce que j’aime bien appeler un framework de commentaire. Voici comment ça marche.

La première étape est d’abord de connaître les conventions de formatage de ce type de commentaire. En gros, vous allez formater vos commentaires afin de séparer correctement les informations, ce qui va vous servir à écrire des commentaires plus pertinents, mais aussi vous imposer un format standardisé que vous allez pouvoir exploiter avec des outils (on verra ça un peu plus loin).

Ces conventions dépendent principalement du langage que vous utilisez. Voici celle pour JavaScript :

/**
 * @summary Ajoute une liste d'aliments au frigot
 * @param {array} food - Liste d'aliments
 */
function fill(food) 
{
    myFood.push(food);
}

Et celle pour C#, que j’utiliserais tout au long de cet article :

/// <summary>
/// Ajoute une liste d'aliments au frigot
/// </summary>
/// <param name="food">Liste d'aliments</param>
public void Fill(List<Food> food) 
{
    MyFood.AddRange(food);
}

Je vous rassure tout de suite, la plupart des IDE génèrent ce format automatiquement, ce qui fait que vous n’avez pas besoin de tout écrire. Encore heureux !

Après, on peut argumenter sur le fait que ce genre de commentaire prend énormément de place, mais étant donné qu’ils sont dans des “zones blanches” (le corps des classes), ils ne se mélangent pas avec les instructions, et donc ne font pas trop tâche. Et puis, il y a toujours de la place pour des bons commentaires !

Une fois le formatage adopté, il faut ensuite déterminer ce que l’on commente (le formatage des commentaires est sensé vous mettre sur la piste).

En fonction de votre manière de commenter, il peut y avoir des subtilités, mais voilà la stratégie de manière générale :

• Classes, propriétés, champs : expliquer ce que c’est et ce que ça représente concrètement. S’ils sont liées à un comportement spécifique, expliquer à quoi elles servent dans le programme.

/// <summary>
/// Toute la nourriture dans le frigot
/// </summary>
public List<Food> MyFood { get; set; }

• Fonctions, méthodes : expliquer à quoi elles servent et leur fonctionnement (traitements effectués). Expliquer chaque paramètre d’entrée un par un, et si nécessaire, expliquer le résultat retourné.

/// <summary>
/// Retire un aliment du frigot
/// </summary>
/// <param name="foodName">Nom de l'aliment à retirer</param>
/// <returns>Aliment retiré</returns>
public Food Retrieve(string foodName) 
{
    foreach (Food food in MyFood) 
    {
        if(food.Name == foodName) 
        {
            MyFood.Remove(food);
            return food;
        }
    }

    return null;
}

Notez que tous les commentaires ne se valent pas. Parfois le programme s’explique de lui-même, et votre commentaire passe comme un mode d’emploi pour utiliser une tasse à café.

Par exemple :

/// <summary>
/// Constructeur complet
/// </summary>
public Food(string name, DateTime expirationDate, PreservationType preservation)
{
    Name = name;
    ExpirationDate = expirationDate;
    Preservation = preservation;
}

/// <summary>
/// Retourne le dernier caractère d'une chaîne
/// </summary>
public static char GetLastCharacter(this string str) 
{
    return str[str.Length - 1];
}

/// <summary>
/// Méthode de conservation de l'aliment
/// </summary>
public enum PreservationType
{
    Fresh,
    Frozen,
    Canned
}

Une fois que vous avez votre formatage et que vous savez quoi commenter, et bien il n’y a plus qu’à le faire.

La règle d’or d’un commentaire, c’est d’être le plus clair et concis possible. Un nouvel arrivant dans le projet doit être en mesure de comprendre le commentaire (sinon ça n’a pas d’intérêt).

Commentaire d’instruction

Le but des commentaires d’instruction est d’expliquer une ligne ou un bloc de code en particulier. Ils se placent à l’intérieur des fonctions, et donc se mélangent avec le code.

On les utilise en général pour détailler le fonctionnement d’une instruction très compliquée ou trop contextuelle afin d’aider le développeur à lire le code. C’est un peu comme une side-note dans la marge d’un livre commenté.

Contrairement aux commentaires de définition, ils n’ont pas de formatage ou de règles particulières. Ce ne sont ni plus ni moins que des mementos.

Quelques exemples :

// En fonction de l'ordre, on trie l'enumerable, puis on le converti en List<string>
List<string> orderedList = (order == "DESC" ? enumerable.OrderByDescending(x => x) : enumerable.OrderBy(x => x)).ToList();

// Si on à affaire à plus de 89 objets, alors on est sur une liste 
// de type C et les objets principals se trouvent sur la plage 89-101
// donc on les déplace au début de la liste.
if(list.Count >= 89)
{
    list.Reverse();
}

Contrairement à la croyance commune, il ne faut pas en abuser. Dans 99% des cas, votre code devrait être capable de s’expliquer de lui-même, et trop de ce genre de commentaires vont plus alourdir le code qu’autre chose.

Beaucoup utilisent ce genre de commentaire pour détailler le fonctionnement d’une fonction, en commentant chaque étape, sauf que non. Un bon commentaire de définition est sensé faire ce travail. Ça passe si vous faites un post sur Stack Overflow, mais dans un vrai programme, vos collègues vont vous étrangler.

Ah oui, et quelque chose que je vois souvent : ne jamais utiliser les commentaires d’instruction pour éclaircir votre code sale ! S’il vous plait. Investissez plutôt votre temps dans sa réécriture plutôt que de recoller les morceaux à coup de commentaire. C’est pire que de réparer un T-Shirt avec du scotch.

Règles

Les 2 types sont là pour vous aider à structurer vos commentaires, mais encore faut-il savoir ce que vous allez y mettre, pourquoi, et pour qui.

Pour le coup, ça va dépendre beaucoup de vous, de votre programme, de votre équipe et de vos exigences, mais voici quelques pistes qui pourront peut-être vous aider.

À qui vous vous adressez ? Parfois, des personnes non-expertes vont être amenées à lire vos commentaires, par exemple, si vous faites une documentation technique pour un client. Dans ce cas, il est important de rester clair et d’éviter au maximum le langage de votre entreprise, et les fameux buzzwords de développeur que l’on aime tant.

/// <summary>
/// Obtient le type du prototype sur une plage X-221 - Z-086
/// </summary>
/// <param name="name">Le nom du prototype</param>
public static string GetPrototypeType(string name)
{
    // Fait un truc
}

/// <summary>
/// Obtient le type (la catégorie et la sous catégorie) du prototype.
/// </summary>
/// <remarks>
/// Cette méthode ne prends en charge que les catégorie X, Y et Z de X-221 à Z-086 (page 661 à 901 du manuel “Engineering Design for Prior tubes and sticks”)
/// Pour plus d'informations sur chaque catégories, consultez la documentation : https://doc.priordid.org/prototype/categories
/// </remarks>
/// <param name="name">Le nom du prototype</param>
/// <return>Type du prototype au format X-YYY</return>
public static string GetPrototypeType(string name)
{
    // Fait un truc
}

Quel niveau de détail ? Est-ce qu’il y a besoin d’expliquer chaque recoin sombre de votre programme, ou une petite ligne vite faite peut faire l’affaire ?

Quelles informations serait-il intéressant de renseigner ? Parfois, il peut-être intéressant d’utiliser les commentaires de définition pour renseigner le ou les auteurs d’une méthode, la date de création et de modification, quelques exemples pour les propriétés un peu complexes, indiquer la source s’il s’agit d’un copié-collé d’un code sur Stack Overflow…

/// <summary>
/// Elimine tous les aliments périmés
/// </summary>
/// <returns>Nombre d'aliment éliminés</returns>
/// <author>DrunkBear44</author>
/// <date>2017-06-23</date>
/// <source>https://stackoverflow.com/questions/18917725/c-sharp-remove-object-from-list-of-objects</source>
/// <exemple>
/// <c>
///     Console.WriteLine(fridge.MyFood.Count); // 13
///     fridge.RemoveAllExpired();
///     Console.WriteLine(fridge.MyFood.Count); // 9
/// </c>
/// </exemple>
public int RemoveAllExpired() 
{
    int i = 0;
    foreach(Food food in MyFood)
    {
        if(food.IsExpired) 
        {
            MyFood.Remove(food);
            i++;
        }
    }

    return i;
}

Pour les conventions d’écriture, c’est à vous de voir, mais l’important est que le commentaire soit écrit de manière concise, et qu’il explique les choses clairement. Si vos commentaires serviront à générer une documentation, faites attention à votre orthographe et votre grammaire. Je sais que c’est dur, mais c’est nécessaire ;)

Commentaires spéciaux

Avant de passer aux outils, je vais faire un petit point important sur les commentaires spéciaux couramment utilisés, qui ne servent pas à documenter un code, mais qui ont d’autres utilités pratiques.

Le code commenté

C’est typiquement ce qui arrive quand on code un algorithme qui, au final, s’avère foireux ou inutile. On le met en commentaire pour éviter de l’utiliser, mais pour quand même en garder une trace au cas où.

// public bool RemoveAllExpired() 
// {
//     bool oneRemoved = false;
//     foreach(Food food in MyFood)
//     {
//         if(food.IsExpired) 
//         {
//             MyFood.Remove(food);
//             oneRemoved = true;
//         }
//     }

//     return oneRemoved;
// }

Alors soyons clair une bonne fois pour toute, votre programme n’est pas un dépotoir ! Si j’avais gagné 1€ à chaque fois que j’ai vu du code commenté pourrir au milieu d’un programme pendant des années sans jamais être utilisé, j’aurais déjà ma villa aux Bahamas.

Je sais que c’est douloureux d’avoir travaillé pour rien, et pour être honnête avec vous, j’en suis le premier fautif. Mais à un moment, ça fait tâche de graisse au milieu de votre programme, et vos collègues et les nouveaux arrivants ne comprennent généralement pas ce que ça fait là. Donc nettoyez-moi ça !

C’est la même chose que de garder des vieilles chaussettes trouées “au cas où elles servent un jour”.

Les instructions

Par là, je parle surtout des commentaires type // TODO ou // A FAIRE.

/// <author>Roger Johnson</author>
public static double Thing(int c) 
{
    // Roger, c'est quoi cette ***** !!!
    var a = c*2;
    var b=14.4;
    var d=4;
    var e=false;
    return e ? a * d + c * 2 + b : a * d + c * a;
}

En soit, l’idée est intéressante puisqu’elle permet de pouvoir parcourir le code avec CTRL + F pour trouver les emplacements où il y a des modifications à apporter.

Mais ils nécessitent des règles strictes et bien précises.

Et oui, parce que si la moitié des développeurs utilisent // TODO, et l’autre moitié // A FAIRE, ça ruine le principe puisqu’on ne sait plus quoi rechercher.

Mon conseil, c’est de vous faire une petite note avec vos collègues où vous allez indiquez les conventions à respecter pour écrire ce genre de commentaire, et vous forcer à les respecter.

Voici un exemple de la convention que j’utilise dans quasiment tous mes projets.

/// <info>...</info> => Besoin d'informations supplémentaire
/// <warning>...</warning> => Le code nécéssite un peu de maintenance/réusinage
/// <error>...</error> => Le code est potentiellement dangereux et doit être corrigé au plus vite
/// <todo>...<todo> => Modifications à apporter dans cette méthode

// INFO ... => Besoin d'informations supplémentaire
// WARNING ... => Cette ligne/bloc nécéssite un peu de maintenance/réusinage
// ERROR ... => Le code est potentiellement dangereux et doit être corrigé au plus vite
// TODO ... => Modifications à apporter ici

Les mises en forme

On a tous déjà vu ou fait un commentaire de ce type-là ou similaire :

/************************************************************/
/*                                                          */
/*              Ajoute un aliment au frigot                 */
/*                                                          */
/************************************************************/
public void Add(Food food) 
{
    MyFood.Add(food);
}

Alors… Primo, non. Et deuzio, non plus.

Je comprends que l’intérêt est de faire ressortir les commentaires les plus importants. Mais si vous respectez correctement les deux types de commentaire et le formatage de vos commentaires de définitions, vous allez être en mesure d’écrire des commentaires propres sans passer par ce genre de… Performances artistiques contemporaines ?

Outils

Dernier, mais pas des moindres. On va maintenant parler des outils qui vont vous permettre de développer plus efficacement grâce à vos commentaires. Peut-être que vous n’êtes pas encore convaincu de l’intérêt de mettre en place un formatage strict et des règles précises pour les commentaires de définition, alors laissez moi ajouter la dernière pierre à l’édifice.

Mise en forme

Pour commencer léger, sur certains IDE, il est possible de gérer la mise en forme des commentaires simplement sans passé par des gros pâtés comme on à vu juste avant.

Ca peut servir à colorier des commentaires pour les mettre en valeur, comme mettre les commentaires très importants en rouge. Ou au contraire, pour les faire plus discret, par exemple, en mettant vos commentaires de définitions (qui prennent quand même beaucoup de place) en gris, pour diminuer la “pollution visuelle”.

Mettre des mots en gras ou en italique via du markdown, ou alors cacher complètement les commentaires si vous jugez qu’ils prennent trop de place.

C’est assez pratique et ça donne une autre utilité aux commentaires, à condition bien sûr que tous les membres de votre équipe utilisent le même outil.

En général, ils prennent simplement la forme d’extensions. Il y en a pour tous les éditeurs : VSCode, Atom, Sublime text…

Auto-compléteur

Certains auto-compléteurs, comme IntelliSense, sont en mesure de lire et d’afficher vos commentaires de définition (sans le formatage) sur-le-champs. Ça marche pour les propriétés, les méthodes, et même les paramètres de méthodes.

C’est super intéressant puisque ça vous permet d’immédiatement comprendre l’utilité d’un membre, au lieu de devoir parcourir vos fichiers pour aller lire le commentaire.

Et c’est encore plus pertinent quand vous utilisez une API ou vous n’avez pas accès au code. Imaginez si à chaque fois que vous voulez utiliser une nouvelle fonctionnalité, au lieu de chercher dans la documentation (s’il y en a une) ou sur les forums type Stack Overflow, vous parcourez juste les membres de l’API avec votre auto-compléteur et vous lisez les commentaires.

Non seulement ça fait gagner un temps fou, mais en plus, vous allez découvrir plein d’autres membres qui pourront être intéressants plus tard, le pied ! Bien sûr, à condition que l’auteur de l’API ait commenté son code correctement.

Vous pourrez trouver ce genre d’outil facilement grâce à des extensions si vous utilisez des éditeurs très populaires. La plupart des IDE intègrent ce genre de fonctionnalité par défaut.

Générateur de documentation

Il n’y a pas d’arnaque, ça fait vraiment ce que vous pensez. Il s’agit de programmes qui vont venir lire vos commentaires de définition, et vous faire une documentation de références avec ça, en HTML la plupart du temps.

C’est une pratique qui est extrêmement courante et qui est utilisée par bon nombre de documentations d’API ultra-connues. Par exemple : la doc Microsoft MSDN à été générée par DocFX, la doc de Vue.js à été générée par Docsify...

En général, on reconnaît ce genre de doc parce que tout y est bien rangé et répertorié en catégories, et, comme par hasard, ces catégories correspondent justement au formatage utilisé pour les commentaires de définition.

/// <summary>
/// Rounds a double-precision floating-point value to a specified number of fractional digits, and rounds midpoint values to the nearest even number.
/// </summary>
/// <param name="value">A double-precision floating-point number to be rounded.</param>
/// <param name="digits">The number of fractional digits in the return value.</param>
/// <returns>The number nearest to value that contains a number of fractional digits equal to digits.</returns>
/// <exception cref="ArgumentOutOfRangeException">digits is less than 0 or greater than 15.</exception>
/// <remarks>
/// The value of the digits argument can range from 0 to 15. Note that 15 is the maximum number of integral and fractional digits supported by the Double type.
/// This method uses the default rounding convention of MidpointRounding.ToEven. See Midpoint values and rounding conventions for information about rounding numbers with midpoint values.
/// </remarks>
public static double Round (double value, int digits);

Imaginez simplement les dizaines, voir centaines d’heures que vous allez économiser en documentant votre API de cette manière, tout ça parce que vous avez décidé d’augmenter la qualité de vos commentaires. C’est juste fou.

Des outils de ce genre, il y en a pour beaucoup de langages. Personnellement, j’utilise énormément DocFX qui est le générateur de documentation de référence pour l’environnement .NET, et qui aura probablement droit à un article sur ce blog.

À vous de jouer

Maintenant que vous savez tout sur comment faire des commentaires parfaits, il ne vous reste plus qu’à appliquer vos connaissances dans votre projet. Bien sûr, le top serait de le faire dès le début, pour pouvoir répartir le travail, mais il n’y a pas d’âge pour commencer, comme le vélo.

D’abord, la première chose à faire, c’est de vous renseigner sur le formatage des commentaires de définition et les bonnes pratiques pour votre langage. Il est hyper-important de suivre les conseils de la communauté si vous voulez que vos futurs outils fonctionnent correctement.

Ensuite, avec votre équipe, mettez en place une stratégie pour vos commentaires. Déterminez le niveau de détail des informations dont vous avez besoin, le registre de langue utilisé (technique ou très simple ?), les informations à indiquer absolument (auteur, date…), le format des instructions (// TODO), etc.

Pensez a tout noter sur un document afin que ça ne se perde pas avec le temps, je pense qu’on connaît tous la chanson.

Profitez aussi de ce temps pour trouver des outils qui viendront exploiter vos commentaires, comme les auto-compléteurs et générateur de documentation.

Enfin, une fois les règles érigées et intégrées par les membres de l’équipe, il ne vous reste plus qu’à les appliquer. Je vous recommande fortement de TOUJOURS commenter immédiatement après avoir fini de coder un membre, car les détails sont encore tout frais dans votre tête.

Et voilà, après, c’est juste une habitude à prendre. Vous verrez que le gain de temps ne sera pas immédiatement visible, et ça peut sembler pénible de passer 30s-1m de plus pour écrire un commentaire de définition.

Mais entre la communication plus simple au sein de l’équipe, la facilité d’intégration des nouveaux développeurs, les outils pour gagner en productivité comme les auto-compléteurs et la génération de documentation automatique, ce sont des dizaines, voir centaines d’heures que vous allez gagner sur le long terme.

Si vous voulez un exemple de code intégralement commenté, allez voir celui que j’ai fait dans mon bonus.

Bon, c’était un long article, mais au moins, je suis sûr que vous avez maintenant toutes les cartes en main pour pouvoir écrire des commentaires de qualité qui en ferait rougir Balzac.

Les commentaires font vraiment partie des bonnes pratiques de la programmation que tout le monde connaît, mais que peu de personnes appliquent correctement, et je pense qu’un petit coup de fouet ne fait pas de mal. Donc si vous avez des amis qui écrivent encore leurs commentaires par-dessus la jambe, rappelez-les à l’ordre en leur partageant cet article ;)

Il y a encore beaucoup de choses à dire sur les bonnes pratiques, je pourrais parler des conventions de nommage, du formatage du code, etc. Ou même détailler les outils donc j’ai parlé au-dessus, comme les auto-compléteurs ou les générateurs de documentation. Bref, ma boite à idées est infinie.

Donc si vous voulez m’entendre plus parler de ces sujets-là, laisser moi un petit commentaire (de blog bien entendu !) en précisant le thème de votre choix et je me ferrais une joie d’écrire à ce sujet.

Accéder au bonus : Un exemple de code C# parfaitement bien commenté.