Lâchez vos coms !

Je sou­hai­te­rais par­ta­ger avec vous dans ce billet quelques petites choses qui relèvent plus de l'anecdote per­son­nelle que de l'article sérieux. J'espère que vous ne m'en vou­drez pas si je prends le risque de bais­ser un peu le niveau de ce blog, mais ça fait un moment que le sujet me trot­tait en tête.

comments
En Python, les com­men­taires com­mencent 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 jour­née avec un col­lègue qui a un bagage très infor­ma­tique. Je me suis vite ren­due compte que nos manières de « pen­ser infor­ma­tique » étaient radi­ca­le­ment dif­fé­rentes, à plu­sieurs niveaux. Par­mi nos diver­gences d'opinion, il y avait la ques­tion des com­men­taires, dont nous avons beau­coup débat­tu.

Per­met­tez-moi d'abord de rap­pe­ler, en gros, ce qu'est un com­men­taire. Il s'agit d'une par­tie du texte d'un pro­gramme qui sera igno­ré à la com­pi­la­tion ou l'interprétation. Le texte est pré­cé­dé ou entou­ré de sym­boles par­ti­cu­liers qui vont signa­ler à la machine qu'elle doit pas­ser son che­min. En géné­ral, comme leur nom l'indique, on y écrit des com­men­taires sur le pro­gramme ou une par­tie de son code.

wtfm
Illus­tra­tion gra­cieu­se­ment prê­tée par Thom Hol­wer­da de osnews​.com

Selon mon col­lègue sus-cité, les com­men­taires sont inutiles si le code lui-même est bien fait. La topo­lo­gie du code, son aéra­tion, ses noms de variables et fonc­tions, etc., devraient être suf­fi­sants pour en déduire faci­le­ment son fonc­tion­ne­ment détaillé.

Il est vrai que la plu­part du temps, un code illi­sible est trop com­pli­qué, com­porte trop de boucles imbri­quées, des noms de variables qui ne donnent aucune indi­ca­tion sur ce qu'elles contiennent, des choses inutiles, est trop tas­sé, mal construit (com­prendre ici un manque de logique et/​ou de cohé­rence dans la sub­di­vi­sion de ses dif­fé­rentes par­ties), trop répé­té, pas modu­laire, et relève mas­si­ve­ment du bri­co­lage et/​ou du tem­po­raire.

Néan­moins, de là à en déduire que l'inverse est vrai, qu'un code « bien écrit » est lim­pide comme de l'eau de (code) source, il y a un pas un peu vite fran­chi. Les com­men­taires existent pour une bonne rai­son.

Lire du code est un exer­cice dif­fi­cile et demande une cer­taine habi­tude. Il est d'autant plus dif­fi­cile 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 for­mu­ler une réponse à une ques­tion. Et si l'auteur ne voit pas du tout les choses comme vous, il est bien dif­fi­cile de lire son code, car rien n'est là où vous l'attendrez. Et il ne s'agit là que d'un pro­blème secon­daire.

Le vrai, le grand méchant pro­blème est d'ordre beau­coup plus prag­ma­tique. Le code tou­jours bien écrit relève de l'Utopie la plus extra­va­gante. Ou du monde des Bisou­nours, je vous laisse le choix de la des­ti­na­tion. Dans la vraie vie, tout le monde fait des com­pro­mis entre temps dis­po­nible et qua­li­té du code, car écrire du code suf­fi­sam­ment propre pour qu'on se voie dedans est géné­ra­le­ment incom­pa­tible avec les notions de dead­line et de pro­grès tech­nique. Si on sou­haite res­ter dans des délais rai­son­nables afin de res­ter à jour dans l'environnement tech­nique dans lequel on évo­lue, on ne peut pas éter­nel­le­ment cou­rir après l'asymptote de la per­fec­tion. Il faut se poser des limites.

À cela s'ajoute le pro­blème des modes et des canons, qui ont une influence consi­dé­rable dans le domaine de la pro­gram­ma­tion. Les desi­gn pat­terns en sont un bon exemple. Il y a tou­jours des gens pour vous dire « c'est comme ça qu'il faut pro­gram­mer X, et pas autre­ment », et ils ne sont par­fois pas du tout d'accord entre eux. Pour­tant, toutes les approches sont inté­res­santes, mais c'est un autre sujet. Ce que cela implique en revanche, c'est que mal­gré tout le soin qu'on puisse appor­ter à la rédac­tion de son code, on ne pour­ra pas plaire à tout le monde, non seule­ment à cause des dif­fé­rentes manières de pen­ser, mais éga­le­ment du fait des dif­fé­rentes écoles qui s'opposent et qui viennent sou­vent com­plexi­fier le code.

Et la bioinfo dans tout ça ?

Sweet Brown and memegenerator.net
Sweet Brown and meme​ge​ne​ra​tor​.net

En bio­in­for­ma­tique, nous héri­tons de tous ces écueils, mais nous ne nous en conten­tons pas. Le sujet y prend une toute autre dimen­sion. Comme il fal­lait en rajou­ter une couche, il se trouve qu'une bonne par­tie du code que nous pro­dui­sons est consti­tué de scripts et de petits pro­grammes des­ti­nés à la recherche et l'analyse de don­nées. Sou­vent, il s'agit de code « jetable », « pro­vi­soire » ou « à mettre au propre » tapé sur un coin de table qui finit par être uti­li­sé sur le long terme car il répond aux besoins du labo­ra­toire pour un ou plu­sieurs pro­jets. Puis arrive le moment où on sou­haite modi­fier ledit code pour le faire évo­luer. Pour peu que le code soit trop vite fait, peu ou pas com­men­té, il arrive régu­liè­re­ment qu'il soit plus inté­res­sant de tout réécrire à par­tir de zéro, au risque de perdre des fonc­tion­na­li­tés inté­res­santes en route. Que de temps per­du !

Du coup, à plus forte rai­son dans ce domaine, il est impor­tant de com­men­ter son code pour per­mettre son évo­lu­tion et sa réuti­li­sa­tion. Mal­heu­reu­se­ment, tous ceux qui ont eu l'occasion de mettre le nez dans les entrailles d'un petit pro­gramme « in-house » ou dans l'implémentation un peu rapide de l'algorithme d'une publi­ca­tion scien­ti­fique inté­res­sante (quand il en existe une) se sont for­cé­ment cas­sé les dents quelque part au moins une fois dans leur car­rière.

À titre illus­tra­tion, et pour vous mettre un peu dans le contexte de ce qui m'a ins­pi­ré cet article, voi­ci un extrait du code source d'un pro­gramme avec lequel je tra­vaille actuel­le­ment, dans le cadre d'un pro­jet de méta­gé­no­mique :

if(Long_Range) {
z[0].lr.r = z[m].rl.r = 1;
z[0].lr.c = z[m].rl.c = 0;
} // end if
else {
z[0].lr.r = z[m].rl.r = 1;
} // end else

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.

Exception up = new Exception("Something is really wrong.");
throw up; //ha ha
stop(); // Hammertime!
long long ago; /* in a galaxy far far away */
options.BatchSize = 300; //Madness? THIS IS SPARTA!
// Replaces with spaces the braces in cases where braces in places cause stasis
$str = str_replace(array("\{","\}")," ",$str);
// Any maintenance developer who can't quote entire Monty Python
// movies from memory has no business being a developer.
const string LancelotsFavoriteColor = "$0204FB"
doRun.run();  // ... "a doo run run".
#Christmas tree initializer
toConnect = []
toRead = [ ]
toWrite = [ ]
primes = [ ]
responses = {}
remaining = {}

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

 

static void happy_meal_tcvr_write(struct happy_meal *hp,
void __iomem *tregs, int reg,
unsigned short value)
{
int tries = TCVR_WRITE_TRIES;

ASD(("happy_meal_tcvr_write: reg=0x%02x value=%04x\n", reg, value));

/* Welcome to Sun Microsystems, can I take your order please? */
if (!(hp->happy_flags & HFLAG_FENABLE)) {
happy_meal_bb_write(hp, tregs, reg, value);
return;
}

/* Would you like fries with that? */
hme_write32(hp, tregs + TCVR_FRAME,
(FRAME_WRITE | (hp->paddr 23) | ((reg & 0xff) 18) | (value & 0xffff))); while (!(hme_read32(hp, tregs + TCVR_FRAME) & 0x10000) && --tries) udelay(20); /* Anything else? */ if (!tries) printk(KERN_ERR "happy meal: Aieee, transceiver MIF write bolixed\n"); /* Fifty-two cents is your change, have a nice day. */

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!



Pour continuer la lecture :


Commentaires

7 réponses à “Lâchez vos coms !”

  1. Com­men­tez votre code comme si la per­sonne char­gée de la main­te­nance était un psy­cho­pathe fou furieux qui connais­sait votre adresse.

    1. Tech­nique inté­res­sante.
      *réflé­chit*
      Adieu monde cruel…

  2. les méthodes sont les habi­tudes de l'esprit, les éco­no­mies de la mémoire et la sym­pa­thie envers les autres !

  3. Je suis bien d'accord qu'un code peut ne pas être évident même s'il est très bien écrit. Par­fois parce que ce qu'il faut faire en com­plexe en termes d'algorithme, ou parce que les don­nées réclament une manip pas évi­dente.

    Pub éhon­tée pour un billet récent sur un sujet proche :
    http://​tout​se​pas​se​com​me​si​.cafe​-sciences​.org/​2​0​1​3​/​0​2​/​0​8​/​d​o​i​t​-​o​n​-​m​o​n​t​r​e​r​-​l​e​-​c​o​d​e​-​i​n​f​o​r​m​a​t​i​q​u​e​-​d​e​s​-​s​c​i​e​n​t​i​f​i​q​u​e​s​-​m​e​m​e​-​s​i​l​-​e​s​t​-​m​o​c​he/

    1. "Mais publier son code, c’est pas un peu mettre #over­ly­ho­nest­me­thods dans ses articles offi­ciels ?" => LOL c'est un peu ça ! Mais ça vaut vrai­ment le coup. Com­bien de papiers décri­vant des méthodes pas­sion­nantes ai-je croi­sés puis mis de côté car l'implémentation de leur algo n'était pas dis­po­nible ? Trou­ver des choses qui marchent c'est bien, mais deman­der aux gens de réin­ven­ter la roue der­riè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 pro­blème ! Mer­ci de l'avoir par­ta­gé !

  4. Tout à fait d'accord, les com­men­taires sont impor­tants, et en pre­mier lieu pour soi-même — en tout cas moi j'ai sou­vent du mal à me com­prendre si je ne mets pas de com­men­taires…

Laisser un commentaire