Quels sont ceux qui, parmis vous qui me lisez, ont déjà reçu durant leurs études un cours intégralement dédié à l’utilisation des commentaires ? Allons, levez la main ! Hum… Ça ne fait pas beaucoup.

En programmation, l’utilisation des commentaires est généralement considérée comme ne nécessitant pas d’explication particulière. Un commentaire, c’est un commentaire, point. Aussi, combien de fois n’ai-je entendu, au cours de mes études, cette phrase : «  Il faut mettre des commentaires  », sans pour aurant qu’on m’explique à quoi servait vraiment un commentaire.

Pourtant, la pratique a montré que si un commentaire pouvait contribuer à faciliter la relecture du code, il pouvait également produire l’effet inverse. Ce qui montre bien que la bonne pratique du commentaire n’est pas si évidente que ça.

En fait, il existe même un débat d’expert entre les partisans de deux extrêmes : ceux qui militent pour l’utilisation systématique et massive des commentaires, et ceux qui prônent leur éradication totale.

Faut-il éradiquer les commentaires ?

Les arguments des deux camps sont à peu près les suivants :

Les commentaires, c’est bien :

• Un code sans commentaire est incompréhensible
• Un code est plus facile à comprendre avec des commentaires
• Les commentaires permettent d’expliquer le propos du code à un plus haut niveau d’abstraction
• Les commentaires permettent de scanner le code
• Il vaut mieux qu’il y en ait trop que pas assez
• De toutes façons, ça ne peut pas faire de mal

Les commentaires, c’est le mal absolu :

• Les commentaires servent juste à répéter le code en moins précis
• Les commentaires rajoutent de la complexité et doivent être maintenus en même temps que le code
• Mal utilisé, un commentaire complexifie la lecture plus qu’il ne la facilite
• Il vaut mieux refactoriser son code que rajouter un commentaire
• Si un développeur ne peut pas rendre son code clair, comment voulez vous qu’il écrive des commentaires clairs ?
• Je dois déjà me casser le c** à lire du code, il faudrait encore que je me coltine les commentaires ?
• Les commentaires sont une perte de ressource
• Les commentaires, c’est pour les newbies

Chacun des camps dispose d’arguments plus ou moins valables. Au delà de ces deux extrêmes, le développeur pragmatique s’attachera à comprendre à quoi servent les commentaires, pour bien les utiliser.

À quoi servent les commentaires ?

Pour mettre les pendules à l’heure, je dirai que les commentaires ne servent pas à :

• Raconter la vie du développeur : C’est marrant comme certains développeurs adorent étaler leurs états d’âmes ou raconter leur soirée dans leur code source. Finalement, un code, c’est un peu comme un journal intime. C’est plein de vie.

  Cela dit, la vie du développeur précédent n’est pas d’une grande aide quand il faut corriger ses anneries.

• Supprimer des bouts de code devenus inutiles : Oui, parce qu’il y a aussi des développeurs qui sont sentimentalement attachés à leur code. Alors, même quand ce code devient inutile, ils n’ont pas le coeur de le supprimer purement et simplement. Ils préfèrent juste le commenter, comme pour en conserver la trace (Pour info, ce trouble porte un nom : la syllogomanie).
• Réécrire le code en langage naturel : Parce que, c’est bien connu, même pour un développeur aguerri, lire du code, c’est dur. Alors, on va être gentil, et lui traduire le truc complet.

  // charge le fichier xml
  $xml = @simplexml_load_file( urlencode( $this->requestUrl ));
  // si le fichier n'a pas été bien chargé
  if( ! $xml ) {
      // récupère la dernière erreur
      $error = error_get_last();
      // enregistre un message de log
      sfContext::getInstance()->getLogger()->err( $error['message'] );
      // déclenche une exception
      throw new FeedburnerApiException( "Erreur de connexion à l'API FeedBurner" );
  }

  Ce genre de commentaire est tout à fait inutile : il alourdit le code source, impose au développeur de lire plus de choses, et n’importe absolument aucune information utile.

• Indiquer qui a introduit telle modification, ou corrigé tel bug :

  if ($i==0) $size = "font-size: 9pt;"; // thibault : fixes #453834
  else $size = "";

  Et les gestionnaires de source, c’est pour les chiens ?

• Trouver un excuse pour écrire un code compliqué : Ouais, d’accord, mon code est incompréhensible, mais c’est pas grave, je l’ai bien commenté.

En revanche, un commentaire sert à :

• Clarifier l’intention du développeur : Les commentaires sont utiles pour expliquer à un haut niveau d’abstraction pourquoi une portion de code a été écrite.
• Répondre à toute question légitime dont la réponse ne se trouve pas dans le code : Mon code est complexe ? J’ai utilisé un algorithme particulier ? Oui, mais il y a une bonne raison, alors, ne refactorisez pas, de toutes façons j’ai déjà testé toutes les solutions plus simples.
• Expliquer quelque chose de vraiment complexe : à condition que cette chose soit légitimement complexe, mais le cas est rare. Dans le cas contraire, mieux vaut simplifier le code d’abord.
• Générer la documentation d’un code réutilisable : dans le cas ou un code est écrit spécifiquement pour être réutilisé (API, bibliothèque de fonctions, framework, etc.), il est fort pratique d’utiliser des commentaires style javadoc pour générer automatiquement la documentation des interfaces publiques.
• Faciliter la lecture du code : Quelques commentaires bien placés peuvent aider à scanner le code et permettre de trouver plus facilement et rapidement la portion recherchée.

Alors, les commentaires, «  c’est mieux quand yen a pas  » ? En fait, point n’est besoin d’être aussi extremiste. En revanche, j’estime qu’il est bon d’écrire son code en partant du principe qu’il devra être compréhensible sans commentaire. C’est un état d’esprit qui ne peut qu’être bénéfique à la qualité et la lisibilité du code.

Seuls devraient être conservés les commentaires qui ne peuvent pas être supprimés, raccourcis ou refactorisés sans impacter sur la bonne lisibilité du code.

Et vous, qu’en pensez vous ? Les commentaires, glop ou pas glop ?

photo credit : next sentence

Il y a des tas de cas où l’anglicisation de notre langue m’énerve. C’est vrai ça, la langue française est belle, bordel ! Autant s’en servir, nan ? Qu’est-ce que c’est que ces parisiens qui parlent français comme s’ils étaient né à New-York ?

À l’eurovision, par exemple. Qui est l’abruti qui a décrété que c’était intelligent de chanter en anglais ? (Bon, je râle, mais en fait, je m’en fout, de l’eurovision. Une chanson reste mauvaise quelque soit la langue dans laquelle elle est chantée^[1] ). Où quand j’entends des jeunes qui se donnent rendez-vous : «  On se voit à quatre heure et demy  » (prononcer «  aïe  »). Ça me fait bien rigoler, tout ça.

Bref ! Oui, vous l’avez deviné, je fais parti de ces agaçants individus qui aiment leur langue, et qui préfèrent utiliser des mots français quand ils peuvent^[2].

En revanche, je considère qu’il y a certains domaines dans lesquels un chauvinisme linguistique exacerbé est franchement déplacé. Qui a envie de parler de «  bogue  » ou de «  fureteur  »^[3], par exemple ? Vous ? Pas moi ! Et surtout, parmi les pires olibrius qui font passer le chauvinisme avant l’intelligence, il y a les développeurs qui codent en français !

Développer en français, une fausse bonne idée ?

À mon sens, coder en français est une idée absurde. La langue française, avec sa complexité et ses subtilités, est particulièrement adaptée pour la poésie et la diplomatie. Mais pas pour développer.

Je suis forcément attristé quand je vois fermer un éditeur de trés bons livres en français. Mais quand on développe, la langue anglaise est tellement plus compacte, tellement plus dénuée d’ambiguités.

Parmi ces deux exemples, lequel est le plus clair ?

function obtenirLaListeDesUtilisateurs() {...
// vs
function getUserList() {...

Alors ?! Hein !? Hein ?! Dites voir un peu ?!

En plus d’être généralement plus verbeuse, la langue française a la triste singularité de faire un usage intensif des particules et des apostrophes. Et les particules et les apostrophes, c’est difficile de les retranscrire en camelCase :

function obtenirLaDateDeLArticle()
// vs
function getArticleDate()

Et les accents ? Comment on fait pour les accents ? Comme si c’était déjà pas assez le bordel avec toutes ces histoire d’encodage (D’ailleurs, même Martine de n’y retrouve plus). Tous les participes passés à la trappe ! Comment on fait la différence entre un présent simple et un participe passé, hein ?! Mettons que je veuille récupérer le dernier utilisateur facturé :

function obtenirDernierUtilisateurFacture() {...

Et le gars qui relit ça, comment il sait si la fonction renvoie une facture ou un utiliseur ? Tandis qu’en anglais :

function getLastFacturedUser() {...

Clair, direct, précis. Sans appel. L’anglais est la langue de l’IT (même si ce n’est pas une raison pour en abuser). Utiliser l’anglais dans son code, ce n’est pas prêter un quelconque serment d’allégeance à la suprématie Étasunienne, ni même faire preuve de snobisme. C’est simplement faire preuve de professionnalisme et reconnaître que la lange anglaise est la référence dans le monde informatique, et qu’elle est mieux adaptée pour écrire un code clair et compréhensible.

Quand aux individus qui font passer leur chauvinisme avant la clarté et la lisibilité de leur code, je vous laisse deviner ce que j’en pense

Notes :

1. Oui, je suis méchant. Et c’est gratuit, en plus. [retour]
2. Vous en connaissez tous. Ils sont vraiment pénibles, n’est-ce pas ? [retour]
3. En revanche, «  courriel  » me plait bien [retour]

photo credit : fredpanassac

Ah ! L’IUT ! Petit moment de nostalgie. Je me remémore mon arrivée dans ce que j’imaginais alors être un temple du savoir, un panthéon de la connaissance. Je me voyais déjà marchant en toge parmis les vénérables érudits qui, au prix d’une vie de labeur et d’intense réflexion, avaient amassé une telle compétence que le simple fait de leur baiser les pieds me remplirait d’honneur et de joie.

Enfin ! Enfin, terminées les pénibles heures, incomfortablement assis devant un cahier à étudier des matières inutiles et obsolètes. Enfin, j’allais pouvoir m’abreuver au calice de la culture informatique. J’allais boire jusqu’à la lie le doux hydromel de cette noble science.

Une larme me monte au yeux lorsqu’à ma mémoire remonte avec nostalgie le souvenir de mon second cours de programmation (le premier était une fabuleuse analogie entre la programmation et le tricot irlandais). Je revois encore l’honorable professeur, barbu et imposant comme il se doit, pénétrer d’un pas sûr et tranquille dans l’amphi bondé, et d’un seul regard, serein mais implacable, imposer le silence aux étudiants.

Après nous avoir considéré quelques secondes, l’éminent docteur, toujours sans dire un mot, se tourne vers l’immense tableau vert, saisi une craie, et commence à écrire. Dans la salle, pas un mot, pas un chuchotement. Nous sommes tous figés, écoutant religieusement les crissements de la craie, attendant ce qui va suivre. Notre curiosité, notre soif d’apprendre sont telles, que nous n’osons presque plus respirer.

Après deux interminables minutes, l’estimable savant pose sa craie, se frotte les mains en se tournant vers nous, nous considère d’un oeil malicieux, et nous lance, narquois : «  Alors, quelque peut-il me dire ce que cela signifie ?  »

void action(int* var1, int* var2) {
    *var1 =  *var1 + *var2;
    *var2 =  *var1 - *var2;
    *var1 =  *var1 - *var2;
}
 
int main() {
    int var1 = 5;
    int var2 = 7;
 
    action(&var1, &var2);
 
    printf("%d %d\n", var1, var2);
}

Après quelques dizaines de secondes à rester dubitatif, observant ces symboles cabalistiques les yeux plissés par l’effort de réflexion, nous dûmes bien avouer notre impuissance à leur attacher un sens.

Amusé, l’honoré pédagogue, celui qu’au fond de nous nous appellions déjà «  maître  », repris sa craie et compléta le blanc qu’il avait judicieusement laissé au tableau.

/*
 * Type : procédure
 * Paramètres : 2 entiers var1 et var2
 * Résultat : Rien
 * Action : cette fonction échange les deux valeurs des variables passées en paramètres,
 * sans utiliser de variable intermédiaire
 */
void action(int* var1, int* var2) {
    *var1 =  *var1 + *var2;
    *var2 =  *var1 - *var2;
    *var1 =  *var1 - *var2;
}
 
int main() {
    int var1 = 5;
    int var2 = 7;
 
    action(&var1, &var2);
 
    printf("%d %d\n", var1, var2);
}

«  Et maintenant, comprenez vous ?  » Évidemment ! L’évidence nous avait sauté aux yeux. Tout était limpide comme de l’eau de source. Fallait-il que nous soyons sots et ignorants pour n’avoir pas compris plutôt ? Ce code échangeait tout simplement les valeurs des deux variables passées en paramètres, sans utiliser de fonction intermédiaire.

«  Sans commentaires, un code est incompréhensible. Dorénavant, vous ajouterez un commentaire devant chaque fonction, pour indiquer son action, ses paramètres, et son retour. Si vous ne vous conformez pas à cette règle, inutile de vous présenter à l’examen  ».

Une fois cette docte sentence prononcée, le vénérable enseignant tourna les talons, et sorti sous nos applausissements déchaînés. En fait, seuls ma pudeur naturelle et les traces de vieux chewing-gums écrasés par terre me retinrent de me jeter à ses pieds pour le supplier de me bénir.

Ça-y-était !!! Nous jouyions dans la cour des grands. Nous n’étions plus de pauvres demeurés, nous savions que chaque fonction doit être précédée d’un long commentaire ! Nous pûmes alors nous rendre sur les forums de développez.com, et étaler ouvertement notre science en méprisant les hérétiques qui ne commentaient même pas leurs fonctions (les fous) !!

Depuis, beaucoup d’eau a coulé sous les ponts

Depuis ce temps béni, quelques longues et pénibles années se sont écoulées. Alors que je commence à accumuler de l’expérience professionnelle (pas beaucoup, mais un peu quand même), ma naïve insouciance d’alors s’efface peu à peu, érodée par les nombreuses occasions que j’ai d’observer le code des autres d’un regard un peu critique.

Tel l’enfant qui découvre que son père n’est pas tout puissant, il me fallut beaucoup de courage pour affronter la détresse qui fut mienne lorsque je fit cette terrible découverte : mon adoré, mon honoré, mon vénérable et vénéré maître avait tort. Car je dus me rendre à l’évidence : les commentaires, c’est mieux quand y-en a pas !

La suite au prochain épisode…