Introduction

Commenter du code, c'est comme nettoyer sa salle de bain : on ne veut jamais le faire, mais ça créer toujours une atmosphère plus plaisante pour ses invités. Comme j'ai récemment adopté comme nouveau mantra d'utiliser des commentaires fréquents et pertinents dans mon code, j'ai passé quelques heures a chercher des articles sur la lisibilité, la réutilisatiion, et des méthodes.

C'est impressionant de voir l'énorme quantité d'information et de débat sur le sujet. En résumé, il y a beaucoup de reflexion, sauf pour les questions fondamentales comme la signification de "fréquent et pertinent". Comme il y a des millions d'avis différents et contradictoires sur la question, j'ai créé ce bref article pour présenter mes trouvailles.

Les types de commentaires

Le commentaire de Code Cela correspond à utiliser des nom de variables descriptif qui soient explicites. C'est une forme minimaliste de commentaires, et ressemble à cela :

Sans information supplémentaire, il est facile de dire que cette fonction va ajouter un utilisateur à une base de donnée, en sauvant son nom et son age. Une implémentation de ceci s'appelle la notation Hongroise [NdT : cf Wikipedia]

Inline Commenting Specifiquement les commentairesà la fin d'une lgne, mais on peut également utiliser ce terme pour parler des commentaires au sein d'une fonction. C'est la forme la plus basique de commentaires.

Commentaires de fonction Ce type de commentaire est trouvé dans les lignes au dessus d'une fonction, et révèle tous les détails nécéssaires sur cette fonction. Cela inclus les paramètres, la valeur retournée, et toutes les étapes logiques et les décisions qui ont été prises :

Commentaire de Classe / Page Commentaire qui porte sur une page ou un bloc de haut niveau (comm une définition de classe). Générallement, ce commentaire donnent une vue généralle de la page/classe, la date des dernières modifications, les fichiers associés, l'auteur et ses coordonnées. En outre, on peut ajouter un bloc général à la fin de chaque page. Kevin a écrit un excellent modèle pour faire ce type de commentaires en utilisant des modèles XHTML.

Commentaires Usuels

Lors d'un developpement en équipe, des moyens standards d'indiquer la prochaine étape dans le processus sont d'excellents outils de communication avec d'autres developpeurs et permettent un travail efficace. Ils sont aussi connus sous le nom de commentaires fonctionnels.

[Les commentaires fonctionnels] servent un seul but : ajouter de la fonctionnalité au processus de developpement.

Bernhard Spuida - The Fine Art of Commenting

Ils ne vous disent rien sur le code, mais apporte de la documentation sur ce qui doit être fait, aussi bien que sur ce qui a été fait. Voici quelques commentaires usuels facile à utiliser dans son code :

• TODO cette phrase clef désigne ce qui doit être accompli et doit être placé sur la ligne ou le futur code devra-t-être. Certains IDE recconaissent cette ligne et peuvent en tirer une liste de chose à faire.
• BUG / FIX indique un bug spécifique, ou la correction d'un bug, à placer au dessus de la ligne à laquelle il se rapporte. En utilisant un software trackant les bugs, après avoir mis un identifiant du bug, il est possible de garder une trace d'où il est apparu et comment il a été réparé.
• TEAMNAME ce commentaire change selon l'équipe / la société, mais attire l'attention d'un certain développeur ou d'une équipe. Par example, indiquer à l'équipe chargée de l'intelligence artificielle pourquoi une décision a été prise à l'aide de ce type de commentaire. Plus d'information la dessus dans The Art of Code Documentation de Drew Sikora.

En plus de ces mots clefs, il existe des programmes qui commentent le code avec des commentaires standard. Laisser ces programmes faire tout le travail peut entrainer quelques erreurs, mais il est toujours interessant d'y jeter un oeil. Deux exemples sont XML Comments et JavaDoc.

Augmenter la lisibilité du code

Dans un monde parfait, lire du code serait comme lire un livre. Malheureusement, le code est écrit pour être executé par un ordinateur, pas pour être lu par des Humains. On ne peut pas lire le code du début à la fin, cela ressemble plus à un "Livre dont vous êtes le héros", obligeant le lecteur à changer de paragraphe toutes les 3 lignes, essayant de ne pas faire tuer le personnage principal. Les commentaires sont un bon outil pour ajouter du contexte au code, pour dire, lorsqu'on change de page, où on se trouve. Avec ceci en tête, voici quelques astuce pour faire un code plus facile à lire.

Paragraphes commentés Ecrire son code et ses commentaires sous forme de paragraphes. Dans 10 Essential Development Practices, Damien Conway suggère de "casser chaque morceau de code en séquences qui accomplissent une tâche simple".

Preceder les commentaires par une ligne blanche Cela permet de créer une séparation distincte entre le code et les commentaires. Et c'est visuellement reposant.

Indenter les commentaires S'assurer que le commentaire possède la même indentation que la ligne à laquelle il se rapporte. En plus, s'assurer que des commentaires de même type s'aligne bien. Par exemple :

Ne pas insulter l'intelligence du lecteur tous les commentaires ne sont pas productifs. Trop de commentaires rendent le code moins compréhensible, et donc moins lisible. Un exemple :

Ce n'est pas du design Souvent on voit des personnes utiliser des caractères spéciaux un peu partout, ce qui n'est vraiment pas nécessaire. Le plus souvent cela distrait l'attention du lecteur de son travail. Rester simple, rester sobre.

Garder un style consistent Il y a plusieurs points de vue sur la bonne façon de commenter un code. Certains pensent qu'un commentaire doit être suffisament détaillé pour qu'un non programmeur puisse comprendre la logique, d'autres pensent qu'il s'agit juste d'un support. Le plus important, je pense, est de rester cohérent de son style. Cela aide le lecteur à savoir à quoi s'attendre en parcourant différents codes.

Commenter en programmant Les chances de commenter un projet d'jà terminé sont minces, il est préferable de commenter le code au fur et à mesure.

C'est une bonne pratique que d'écrire les commentaires en même temps (ou avant) d'écrire le code.

MSDN - Using Comments Effectively

Commenter pendant que l'on code oblige à s'assurer que la logique "sonne bien". En outre, les commentaires seront plus précis quand le contexte et ce qui se passe dans les coulisse est clair dans son esprit.

Réutilisation du code

Le concept le plus intéressant que j'ai rencontré pendant mes lectures sur les commentaires est "la réutilisabilité du code". C'est quelque chose à laquelle on pense toujours en écrivant du code à balise, et du CSS pour minimiser la charge de travail à faire quand des changements sont faits. Le même principe fonctionne très bien en commentant. Voici un exemple : imaginons que nous avons un textbox en train d'être modifiée :

le simple commentaire sur cette ligne n'est pas réutilisable. Si nous changions la textbox pour un menu déroulant? Il faudrait changer le commentaire. En regardant des pratiques de code, je suis tombé sur une autre question : Est-il acceptable de commenter la fin d'un bloc de code, comme ceci :

Je reste mitigé sur cette question. Avec des IDE modernes qui dessine des lignes en fonction de l'indentation, il n'est pas nécessaire de commenter la fin de chaque bloc. Il y a cependant un bénéfice à commenter la fin d'une fonction. Une fonction reste habituellement en place, mais les blocs logiques sont modifiés jusqu'à ce que tous les bugs soient corrigés. Comme il y a en général beaucoup de bloc dans un document, la phase de commentaire peut devenir très lourde sans avoir à ajouter plein d'informations inutiles.

En parlant de commentaires, Cprogramming.com a écrit "Comment et pourquoi commenter", qui souligne l'importance d'utiliser des noms de variables réutilisables dans les fonctions. Ils ont pour exemple une fonction qui calcule une vitesse. Au, lieu de déclarer la fonction ainsi :

Il est préferable de le rendre réutilisable en renommant les variables génériquement :

De fait, il est possible de calculer la distance pour n'importe quel objet, comme un avion, un train, un sportif, et pas juste une voiture.

A présent, par rapport a la notation Hongroise, il est important de préciser que le sujet est controversé, et soulève des débats houleux. The Good, The Bad and The Ugly pense qu'il n'est pas nécessaire de changer le nom d'une variable chaque fois que celle ci change de type. Par exemple, sEvenement ne doit pas être renommé nEvenement si la variable devient un entier au lieu d'un string.

Indépendamment de son choix, il est important de se souvenir de prendre la réutilisabilité en compte dans ses commentaires. Le plus réutilisables ils sont, le moins de temps il faudra passer dessus. Plus important, quand un membre d'une équipe modifie le code, la plupart du temps, il n'aura pas à chercher parmis tous les commentaires pour chercher ce qu'il y a à changer.

Pourquoi s'en soucier?

L'un des plus grande difficulté pour commenter son code et de se convaincre de le faire, il est donc important de regarder les différentes sources de motivation.

Avant tout, une documentation abondante et claire est un élément clé dans la création d'applications qui puissent vivre et s'adapter.

Jef Raskin - Comments Are More Important Than Code

Sur un plan plus personnel, après avoir appliqués mes découvertes a quelques uns de mes récents projet, j'ai remarqué de nettes amélioration dans mon processus de programmation.

J'écrivais un meilleur code

En commentant tout, j'étais forcé de penser à ce que j'étais en train de faire, plutôt que juste le faire fonctionner. Je programmais de manière reflechie plutot que difficile. Parce que commenter mon code m'obligeais à mettre ma logique par écrit et me faisais réflechir deux fois à mes actions. Je trouvais générallement des manières d'optimiser mon code lorsqu'il ne sonnait pas juste. Les commentaire entraine une optimisation accrue et au final moins de travail. Si j'avais attendu d'avoir fini mon code pour le commenter, je suis positivement sûr que j'aurais perdu beaucoup de temps à reprogrammer et reccomenter mes erreurs de logique. Le temps seul dira si cela baisse le nombre de bugs.

J'améliorais le futur

On ne sais jamais qui pourrais regarder dans son code, ou quand on devra y revenir. Moi-même dans le futur, mes collègues, de potentiels employés, ou même ma mère apprécieront beaucoup le temps passé à commenter, car cela leur sauvera du temps. Le temps c'est de l'argent (surtout en programmation), et eviter d'en gacher sur la compréhension et l'interpretation du code vaut de faire un effort.

J'étais fier de mon travail

L'un de mes plus grands problèmes dans la vie est de travailler sur la même chose jour et nuit. Si je suis fier de ce que je fais, cela enlève ce blocage mental. Comme mes projets étaient propres, efficaces, et sexy, j'ai beaucoup aimé y revenir et cela, d'après moi, n'a pas de prix. Egalement, cela rend les choses bien plus facile pour donner une bonne première impression lors d'un entretien, à des investisseurs ou a des lecteurs de blog obsessionels-compulsifs quand le code a été d'une façon consistente et professionelle.

Voyez par vous même

J'ai écrit une fonction simple en JavaScript pour illustrer comment, même si l'on pense que tout commentaire est important, de mauvaises décisions peuvent dégrader la lisibilité du code. Voici le résultat :

//-+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_-
// j'ai écrit ce script pour gérer une bataille entre deux unités.
// La fonction membre "attaque" fait les calculs mais cette
// fonction détermine l'ordre des attaques.
// Deux objets valides doivent être passés en paramètre à la fonction
// qui renvoie "true" si tout s'est bien passé.
//-+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_-
function beginBattle(attaquant, defenseur) {
    var b; // boolean pour stoquer vie ou mort
    var teamCount; // compteur pour les boucles
    if(defenseur.agilite > attaquant.agilite) {
        b = defenseur.attaque(attaquant);
    }
    // Si il y a eu une première attaque, s'assurer qu'il est toujours en vie avant de continuer
    if(b) {
        b = attaquant.attaque(defenseur);
    }
    // verifier si un partenaire veut contre-attaquer
    // boucler sur les partenaires du defenseur en partant de i = 0
    for(teamCount = 0; teamCount < defenseur.team.length; teamCount++) {
        var partenaire = defenseur.team[teamCount]; // partenaire
        if(partenaire.contreAttaque == 1) { // 1 signifie qu'il peut contre-attaquer
            b = partenaire.attaque(attaquant);
        }
    }
    // s'assurer que la mort est gérer quelque part par ici.
    return true;
} // end function


Cela n'est pas terrible, mais on peut l'améliorer. En utilisant exactement la même fonction, et en applicant quelques methodes décrites ci-dessus :

/*
* Résumé: Determiner l'ordre des attaques, et declencher chaque combat
* Parameters: Objet "creature" representant l'attaquant | Objet "creature" représentant le defenseur
* Return: Booleen indiquant le succes du combat
* Author: Ryan Campbell
*/
function beginBattle(attaquant, defenseur) {
    var enVie; // Booleen indiquant la vie ou la mort après une attaque
    var teamCount; // Compteur de boucle

    // Test d'esquive avant un combat
    if(defenseur.agilite > attaquant.agilite) {
        enVie = defenseur.attaque(attaquant);
    }

    // Continuer l'attaque principale si l'attaquant est toujours en vie
    if(enVie) {
        enVie = attaquant.attaque(defenseur);
    }

    // Verifier si un partenaire du defenseur peut lancer une contre-Attaque
    for(teamCount = 0; teamCount < defenseur.team.length; teamCount++) {
        var partenaire = defenseur.team[teamCount];
        if(partenaire.contreAttaque == 1) {
            enVie = partenaire.attaque(attaquant);
        }
    }

    // TODO: Créer un bloc pour gérer la mort de l'un des deux combattants

    return true;
} // End beginBattle

A mon avis, le code est devenu plus agréable à lire avec des changements minimes. D'abord, nous avons appliqué de la consistence. Tous les commentaires ont une ligne vide avant eux, commencent avec une majuscule, et sont indentés proprement. Ensuite, les variables comme 'b' ont été renommé ('enVie') pour les rendre plus explicites. Enfin, le mot clef "TODO" a été ajouté pour indiquer un changement à faire. En utilisant un langage bref et consistent, j'ai bein amélioré la lisiblité du code.

Créer son propre style

A présent, il y a un mouvement de programmeurs qui pensent que le code est essentiellement une nouvelle forme d'expression personnelle, et il est donc important pour moi d'insister sur le fait que ce ne sont pas ici des idées et stratégies uniques pour bien commenter son code. EN fait, chacun doit partir en ayant compris que les commentaires sont important car ils affectent la lisibilité, les performances et le professionalisme du developpement. Je reccomende que chacun prenne un peu de temps pour reflechir et créer des methodes de commentaires basé sur ce qu'il trouve important dans sa propre situation.

Si vous voulez plus d'information sur ce sujet, je vous suggère de lire tous les liens évoqués au long de cet article. Et même si je ne l'ai pas lu moi même, j'ai entendu beaucoup de bien sur Literate Programming de Donald E. Knuth. Comme toujours si vous avez de bonnes idées pour commenter votre code, faites en profiter tout le monde.

Commenting your code is like cleaning your bathroom—you never want to do it, but it really does create a more pleasant experience for you and your guests.

Ryan Campbell