Accessibility Tools

- Le blog participatif de bioinformatique francophone depuis 2012 -

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 :

Il s'agit d'un bel exemple de ce qu'il ne faut pas faire. Le code est obs­cur, et les com­men­taires n'expliquent rien et enfoncent des portes ouvertes. Si je vous dis que la tota­li­té du code a à peu près la même allure, vous aurez une idée de l'étendue de ma frus­tra­tion lorsque j'ai dû modi­fier de nom­breux élé­ments pour qu'il accepte d'être com­pi­lé sur une machine très dif­fé­rente de celle qui l'a vu naître, tout en m'assurant de ne pas modi­fier son com­por­te­ment.

En revanche, même s'il y a de très bons exemples de code bien com­men­té, 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 consen­sus par­mi les déve­lop­peurs. À mon humble avis, il revient à cha­cun de trou­ver une manière intel­li­gente, élé­gante et rai­son­nable de com­men­ter son code, en fonc­tion de sa mor­pho­lo­gie, de sa logique, de sa dif­fi­cul­té, du contexte, du sens du vent et de l’âge du capi­taine. Il faut juste ne pas perdre de vue les erreurs à ne pas com­mettre, et tâcher de les évi­ter au maxi­mum.

Chers amis bio­in­for­ma­ti­ciens, com­men­tez-donc votre code ! Il pour­rait ain­si rendre ser­vice à quelqu'un d'autre à l'avenir, et peut-être même à vous-même. Car soyons hon­nêtes, nous avons tous un jour ré-ouvert un de nos vieux pro­grammes en nous disant : « Mais kess­ke­jai­vou­lu­faire ??? » Et je ter­mi­ne­rai cette enclume par un petit recueil de com­men­taires et bouts de code qui valent leur pesant de caca­huètes, car don­ner le sou­rire à celui qui relit votre code, ce n'est pas inter­dit pour autant.

Extrait du code du noyau Linux, dri­ver de la carte réseau suc­cé­dant à la carte "Big MAC":

Trou­vés sur le son­dage sui­vant sur Sta­ckO­ver­flow :

http://​sta​cko​ver​flow​.com/​q​u​e​s​t​i​o​n​s​/​1​8​4​6​1​8​/​w​h​a​t​-​i​s​-​t​h​e​-​b​e​s​t​-​c​o​m​m​e​n​t​-​i​n​-​s​o​u​r​c​e​-​c​o​d​e​-​y​o​u​-​h​a​v​e​-​e​v​e​r​-​e​n​c​o​u​n​t​e​red

Un grand mer­ci à Yoann M., Estel, Haut­bit, tadai­ma et Guillaume Col­let pour leur relec­ture, cor­rec­tions et remarques construc­tives !

Vous avez aimé ? Dites-le nous !

Moyenne : 0 /​ 5. Nb de votes : 0

Pas encore de vote pour cet article.

Partagez cet article



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

Pour insérer du code dans vos commentaires, utilisez les balises <code> et <\code>.