Opinion :
Lâchez vos coms!

Je souhaiterais partager avec vous dans ce billet quelques petites choses qui relèvent plus de l'anecdote personnelle que de l'article sérieux. J'espère que vous ne m'en voudrez pas si je prends le risque de baisser un peu le niveau de ce blog, mais ça fait un moment que le sujet me trottait en tête.

comments

En Python, les commentaires commencent par un dièse

Les commentaires sont nos amis, il faut les aimer aussi

Il y a quelques temps, j'ai eu un petit débat de fin de journée avec un collègue qui a un bagage très informatique. Je me suis vite rendue compte que nos manières de « penser informatique » étaient radicalement différentes, à plusieurs niveaux. Parmi nos divergences d'opinion, il y avait la question des commentaires, dont nous avons beaucoup débattu.

Permettez-moi d'abord de rappeler, en gros, ce qu'est un commentaire. Il s'agit d'une partie du texte d'un programme qui sera ignoré à la compilation ou l'interprétation. Le texte est précédé ou entouré de symboles particuliers qui vont signaler à la machine qu'elle doit passer son chemin. En général, comme leur nom l'indique, on y écrit des commentaires sur le programme ou une partie de son code.

wtfm

Illustration gracieusement prêtée par Thom Holwerda de osnews.com

Selon mon collègue sus-cité, les commentaires sont inutiles si le code lui-même est bien fait. La topologie du code, son aération, ses noms de variables et fonctions, etc., devraient être suffisants pour en déduire facilement son fonctionnement détaillé.

Il est vrai que la plupart du temps, un code illisible est trop compliqué, comporte trop de boucles imbriquées, des noms de variables qui ne donnent aucune indication sur ce qu'elles contiennent, des choses inutiles, est trop tassé, mal construit (comprendre ici un manque de logique et/ou de cohérence dans la subdivision de ses différentes parties), trop répété, pas modulaire, et relève massivement du bricolage et/ou du temporaire.

Néanmoins, de là à en déduire que l'inverse est vrai, qu'un code « bien écrit » est limpide comme de l'eau de (code) source, il y a un pas un peu vite franchi. Les commentaires existent pour une bonne raison.

Lire du code est un exercice difficile et demande une certaine habitude. Il est d'autant plus difficile de lire le code de quelqu'un d'autre, car il y a à peu près autant de manières d'écrire du code que de manières de formuler une réponse à une question. Et si l'auteur ne voit pas du tout les choses comme vous, il est bien difficile de lire son code, car rien n'est là où vous l'attendrez. Et il ne s'agit là que d'un problème secondaire.

Le vrai, le grand méchant problème est d'ordre beaucoup plus pragmatique. Le code toujours bien écrit relève de l'Utopie la plus extravagante. Ou du monde des Bisounours, je vous laisse le choix de la destination. Dans la vraie vie, tout le monde fait des compromis entre temps disponible et qualité du code, car écrire du code suffisamment propre pour qu'on se voie dedans est généralement incompatible avec les notions de deadline et de progrès technique. Si on souhaite rester dans des délais raisonnables afin de rester à jour dans l'environnement technique dans lequel on évolue, on ne peut pas éternellement courir après l'asymptote de la perfection. Il faut se poser des limites.

À cela s'ajoute le problème des modes et des canons, qui ont une influence considérable dans le domaine de la programmation. Les design patterns en sont un bon exemple. Il y a toujours des gens pour vous dire « c'est comme ça qu'il faut programmer X, et pas autrement », et ils ne sont parfois pas du tout d'accord entre eux. Pourtant, toutes les approches sont intéressantes, mais c'est un autre sujet. Ce que cela implique en revanche, c'est que malgré tout le soin qu'on puisse apporter à la rédaction de son code, on ne pourra pas plaire à tout le monde, non seulement à cause des différentes manières de penser, mais également du fait des différentes écoles qui s'opposent et qui viennent souvent complexifier le code.

Et la bioinfo dans tout ça?

En bioinformatique, nous héritons de tous ces écueils, mais nous ne nous en contentons pas. Le sujet y prend une toute autre dimension. Comme il fallait en rajouter une couche, il se trouve qu'une bonne partie du code que nous produisons est constitué de scripts et de petits programmes destinés à la recherche et l'analyse de données. Souvent, il s'agit de code « jetable », « provisoire » ou « à mettre au propre » tapé sur un coin de table qui finit par être utilisé sur le long terme car il répond aux besoins du laboratoire pour un ou plusieurs projets. Puis arrive le moment où on souhaite modifier ledit code pour le faire évoluer. Pour peu que le code soit trop vite fait, peu ou pas commenté, il arrive régulièrement qu'il soit plus intéressant de tout réécrire à partir de zéro, au risque de perdre des fonctionnalités intéressantes en route. Que de temps perdu !

Du coup, à plus forte raison dans ce domaine, il est important de commenter son code pour permettre son évolution et sa réutilisation. Malheureusement, tous ceux qui ont eu l'occasion de mettre le nez dans les entrailles d'un petit programme « in-house » ou dans l'implémentation un peu rapide de l'algorithme d'une publication scientifique intéressante (quand il en existe une) se sont forcément cassé les dents quelque part au moins une fois dans leur carrière.

À titre illustration, et pour vous mettre un peu dans le contexte de ce qui m'a inspiré cet article, voici un extrait du code source d'un programme avec lequel je travaille actuellement, dans le cadre d'un projet de métagénomique :

Il s'agit d'un bel exemple de ce qu'il ne faut pas faire. Le code est obscur, et les commentaires n'expliquent rien et enfoncent des portes ouvertes. Si je vous dis que la totalité du code a à peu près la même allure, vous aurez une idée de l'étendue de ma frustration lorsque j'ai dû modifier de nombreux éléments pour qu'il accepte d'être compilé sur une machine très différente de celle qui l'a vu naître, tout en m'assurant de ne pas modifier son comportement.

En revanche, même s'il y a de très bons exemples de code bien commenté, tout est une affaire de préférences. Je ne m'étendrai donc pas sur l'analyse des méthodes qui font plus ou moins consensus parmi les développeurs. À mon humble avis, il revient à chacun de trouver une manière intelligente, élégante et raisonnable de commenter son code, en fonction de sa morphologie, de sa logique, de sa difficulté, du contexte, du sens du vent et de l’âge du capitaine. Il faut juste ne pas perdre de vue les erreurs à ne pas commettre, et tâcher de les éviter au maximum.

Chers amis bioinformaticiens, commentez-donc votre code ! Il pourrait ainsi rendre service à quelqu'un d'autre à l'avenir, et peut-être même à vous-même. Car soyons honnêtes, nous avons tous un jour ré-ouvert un de nos vieux programmes en nous disant : « Mais kesskejaivoulufaire ??? » Et je terminerai cette enclume par un petit recueil de commentaires et bouts de code qui valent leur pesant de cacahuètes, car donner le sourire à celui qui relit votre code, ce n'est pas interdit pour autant.

Extrait du code du noyau Linux, driver de la carte réseau succédant à la carte "Big MAC":

 

Trouvés sur le sondage suivant sur StackOverflow:

http://stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered

Un grand merci à Yoann M., Estel, Hautbit, tadaima et Guillaume Collet pour leur relecture, corrections et remarques constructives!

  • À propos de
  • Ingé Inria Bordeaux, je mets des conteneurs sur une baleine en espérant que ça tienne.

    J'écris aussi des articles ici, quand je peux. Enfin je fais du peu que je mieux.

7 commentaires sur “Lâchez vos coms!

  1. http://geekandpoke.typepad.com/.a/6a00d8341d3df553ef017c3712adb0970b-pi

  2. Commentez votre code comme si la personne chargée de la maintenance était un psychopathe fou furieux qui connaissait votre adresse.

    • Technique intéressante.
      *réfléchit*
      Adieu monde cruel...

  3. les méthodes sont les habitudes de l\'esprit, les économies de la mémoire et la sympathie envers les autres!

  4. Je suis bien d\'accord qu\'un code peut ne pas être évident même s\'il est très bien écrit. Parfois parce que ce qu\'il faut faire en complexe en termes d\'algorithme, ou parce que les données réclament une manip pas évidente.

    Pub éhontée pour un billet récent sur un sujet proche :
    http://toutsepassecommesi.cafe-sciences.org/2013/02/08/doit-on-montrer-le-code-informatique-des-scientifiques-meme-sil-est-moche/

    • \"Mais publier son code, c’est pas un peu mettre #overlyhonestmethods dans ses articles officiels ?\" => LOL c\'est un peu ça! Mais ça vaut vraiment le coup. Combien de papiers décrivant des méthodes passionnantes ai-je croisés puis mis de côté car l\'implémentation de leur algo n\'était pas disponible? Trouver des choses qui marchent c\'est bien, mais demander aux gens de réinventer la roue derrière, c\'est se tirer une balle dans le pied...

      Très bon billet qui mérite d\'être lu, on dézoome encore sur le problème! Merci de l\'avoir partagé!

  5. Tout à fait d\'accord, les commentaires sont importants, et en premier lieu pour soi-même - en tout cas moi j\'ai souvent du mal à me comprendre si je ne mets pas de commentaires...

Laisser un commentaire