Je documente mon code !

Par Emmanuel Deloget, vendredi 21 juillet 2006 à 07:15 :: Expériences :: permalien #5

Tags: bonnes pratiques, commentaire, fun

Enfin, j'essaie...

Documenter le code permet de le rendre plus lisible, me dit on, et pourtant mon intuition est que si seul le code illisible a besoin de documentation alors ecrire du code lisible ne nécessite pas l'écriture de commentaires particuliers. Bien évidemment, je me dois d'être plus nuancé dans mes propos : le code décrit la manière dont ont fait les choses, tandis que le but du commentaire est de décrire l'intention du programmeur.

Si je parle aujourd'hui de ce sujet particulier, c'est parce que le code que je voit actuellement me frappe : trop souvent, les commentaires qu'on découvre - que nous les ayons écrit ou que nous les trouvions dans le code écrit par quelqu'un d'autre - sont des redites du code, qui n'ont qu'une faible valeur ajoutée. J'en ai encore un exemple^[1] sous les yeux au moment où j'écrit ce billet :

  // read abbreviation mapping
  if (!ReadAbbreviationMapping(fileName, fileDir)) {
     return false;
  }

Discutable, n'est-ce pas ? Pourtant, c'est la majorité de nos commentaires qui ressemblent à celui-là, et seule une minorité est intrisèquement utile. Relisez votre code, et vérifier : vous aussi, vous avez une bonne partie de commentaires inutiles.

Pourtant, si une discussion doit s'ouvrir, aucun programmeur ne dira qu'un tel commentaire est utile et qu'il vaut mieux ne pas en mettre. Tous diront qu'un commentaire se doit d'être une explication de pourquoi le code a été écrit de telle ou telle manière, et que paraphaser le code existant est une perte de temps. Alors, pourquoi est-ce que j'ai écrit ce commentaire ?

Tout simplement parce que je sais en mon for intérieur que je dois documenter mon code. Et comme celà me parait étrange d'avoir des fonctions sans aucune ligne de commentaire, j'ajoute des commentaires inutiles et verbieux dans le seul but de satisfaire mon inconscient. Une fois le commentaire ajouté, je sais qu'il ne sert à rien, mais il est là - et sur le moment, c'est bien plus important : j'ai la satisfaction du travail effectué. Bien sûr, je suis de mauvaise foi mais je suis capable de passer outre. Et puis, j'ai une dent contre les commentaires.

Au final, j'ai mes 30%^[2] symboliques de commentaire (un bon pourcentage, qui prends en compte les entêtes de fichier et les entêtes de fonction) et je suis, au moins en apparence, content. Plus important, mon client, voyant les métriques du projet, voit lui aussi que le code est a priori bien documenté, et lui aussi est content.

Et si tout le monde est à peu près content, que demander de plus ? Je veux dire, à part de commentaires utiles?

Notes

[1] tiré du projet sur lequel je travaille actuellement - il s'agit donc bien de code de production, et non pas d'un projet annexe. Non, je ne suis pas fier.

[2] étrangement, la majeure partie des projets sur lesquels j'ai travaillé on des statistiques similaires. J'y vois là le signe qu'on peut en tirer un bon sujet d'étude, à garder sous le coude pour un futur billet.

Trackbacks

Aucun trackback.

Les trackbacks pour ce billet sont fermés.

Commentaires

1. Le vendredi 21 juillet 2006 à 07:52, par Christophe Moustier

Parmi les commentaires "utiles" car à forte valeur ajoutées, on trouve les commentaires liés à des outils de génération de documentation tels que doxygen (www.doxygen.org).

2. Le vendredi 18 août 2006 à 09:26, par Emmanuel Deloget

Il me vient une idée : il pourrait se réveler interressant de voire quelle est notre vision personnelle de ce qu'est un "commentaire utile".

Pour ma part, plus je code et plus je crois que le code n'a qu'un besoin minimal de commentaires. En appliquant des règles simples, on peut assurer un découpage assez précis des fonctions de manière à n'avoir que des fonctions qui sont relativement courtes. Avec un bon nommage, ces fonctions deviennent assez triviales, et il n'est pas besoin de les commenter (excepté via un header de fonction, qui peut préciser le rôle de chaque argument et, dans les cas les plus complexes, donner des indications sur l'algorithme utilisé et sur le but vértable de la fonction).

Reste quelques cas particuliers qui peuvent (exceptionnellement) nécessiter des commentaires à l'intérieur même de la fonction - dans le cas ou la fonction reste longue, malgré tous les efforts pour la couper en plusieurs fonctions. Dans ce cas, il faut éviter de décrire ce que le code fait et insister sur la fonction qu'il réalise. Seules les parties non triviales doivent être documentés (par exemple, les boucles complexes).

D'autres idées ?

3. Le samedi 14 octobre 2006 à 05:07, par Karim Refeyton

Aïe aïe aïe !
Cet article est l'illustration même de deux problèmes trop souvent rencontrés au sein d'équipes de développements :
1- le développeur développe AVANT de réfléchir à la solution
2- le développeur croit qu'un commentaire est une REDITE du code en bon français

J'aimerai rappeler ici, et je ne cesse(rai) jamais de le dire à mes équipes, que :
1- il faut réfléchir à la solution et la valider AVANT de la coder (on créé le squelette des méthodes et ont remplit leur corps de commentaires décrivant l'algorithme étape par étape ce qui permet de valider/retoucher/affiner de manière itérative la solution sans être passé à la phase d'implémentation).
2- le code est la concrétisation en "langage informatique" de l'intention préalablement exprimée en langage naturelle sous la forme du commentaire juxtaposé et non l'inverse

De ces deux principes on en déduit que :
- un commentaire est toujours utile ne serait-ce que parcequ'il justifie le code qui le suit
- il est tout à fait compréhensible d'avoir un commentaire conséquent pour plusieurs lignes de code et non une ligne de commentaire pour une ligne de code

Donc dites-vous bien que si vous vous posez la question "est-il utile de mettre un commentaire", c'est qu'il est déjà trop tard... vous avez mis la charrue avant les boeufs.

J'ajouterai que le fait que le code soit soumis à l'examen d'un outil d'analyse faisant resortir un ratio lignes de commentaire/lignes de code n'a jamais été un gage de qualité. Seule une analyse par sondage aléatoire sur des échantillons représentatifs de code permet de se faire une idée de la clareté et de la "compréhensibilité" a posteriori d'un code, facteur au combien significatif lorsque l'on est chargé de sa maintenance.

4. Le lundi 16 octobre 2006 à 22:09, par Emmanuel Deloget

Je ne peux qu'acquiescer. A ma grande honte, lorsque j'ecris du code, je pense code d'abord et commentaire ensuite - probablement un artefact de pensée, quelque chose du style "mon code est clair, et je sais ou je vais". De temps en temps, j'imagine la colére de celui qui me relit.

Heureusement, je n'ecrit pas beaucoup de code :)

Votre commentaire contient d'autres informations importantes, comme cette notion qui consisterait peu ou prou à ecrire ce que fait la fonction en language naturel pour ensuite en d2river le code. C'est une approche très sensée, à laquelle je n'avais pas pensé auparavant. Celà rend effectivement les commenaires plus clairs. puisque comme vous le rappelez, ils décriventl'intention et non plus le code. La règle est très pratique - d'ailleurs, je vais la ranger de ce pas dans ma toolbox de bonnes pratiques. Merci pour avoir l'avoir partagé ici!

5. Le jeudi 19 octobre 2006 à 11:02, par Stéphane MORAT

Je ne suis pas d'accord avec Karim.

- Les commentaires comme le nom l'indique doivent être écrits après le code qu'ils commentent.
- Si tu valide/retouche/affine, les commentaires ont de grande chance de ne plus être à jour.
- Le langage "naturel" du programmeur est le langage de programmation et pour réflèchir à la soution, il doit penser à l'intéraction entre les objets,
l'encapsulation... Cette manière de sérialiser l'algorithme de la façon dont tu le décrit n'aide pas à penser "objet" mais "procédurale".
- Tous les commentaires utiles écrits avant peuvent l'être aprés, l'inverse n'est pas vrai.

Je suis pour un minimum de commentaire, uniquement pour les besoins de la génération automtaique des documents techniques, pour les algo, pour les choix d'implémentation à justifier, les optimisation effectués,
les syntaxes peu clair(en particulier en C++) et ceux pour faire plaisir au chef.

Je préfere utilser d'autres mesures qualimètriques comme le nombre moyen de méthodes implémentées par classe, le nombre moyen d'instruction par méthode, la compléxité maximale (cf Code Complete - Steve McConnell)) ou la profondeur maximale.

6. Le dimanche 22 octobre 2006 à 18:00, par Karim Refeyton

Bonjour,

Je comprends le point de vue de Stéphane sans toute fois être entièrement d'accord (à quoi serviraient les blogs sinon :) et merci à Emmanuel de nous offrir cet espace).

Tout d'abord, je relèverai que Stéphane confond le langage de programmation et la logique de programmation.

Si le langage utilisé peut être considéré comme une connaissance commune au développeur réalisant le code et à celui en faisant la maintenance par la suite, la logique d'implémentation ne l'est pas : un code peut sembler lisible à l'auteur et incompréhensible au lecteur voire à l'auteur lui-même quelques mois ou années après.

Pourquoi ? Parce que sur le moment, l'auteur baigne dans la problématique qu'il doit appréhender et résoudre. Tout ce qu'il écrit/code lui semble donc naturel dans l'instant. Or lorsqu'une personne vient lire le résultat de votre travail, elle n'a pas effectué le même raisonnement que vous et peut donc ne pas comprendre votre solution. Le résultat n'est pas forcément auto-démonstratif. La documentation du code est donc bien là pour permettre au lecteur de comprendre a posteriori ce que vous avez fait.

(Attention, je ne parle pas ici de la documentation utilisateur d'un logiciel, driver, api... qui ne doit pas révéler les secrets de conception et les impératifs et imprévus ayant conduit à la solution, mais bien de la documentation interne des sources d'un programme dans le but de faciliter sa conception et sa maintenance)

Egalement, il me semble opportun de différencier documentation intégrée au code et commentaire ligne à ligne. La documentation intégrée au code est l'ensemble du contenu textuel intégré dans les fichiers sources. Elle comprend des commentaires portant sur un paquetage (au sens UML), sur une classe, une méthode/message, une propriété/attribut... et au niveau de granularité le plus fin, le commentaire ligne à ligne.

S'imposer de commenter ligne à ligne n'a que peu d'intérêt et occasionne souvent des commentaires écrits dans un style télégraphique impropre à la relecture, ou des redites entre les commentaires et le code que le relcteur zappera de toute façon.

Comme je l'écrivai précédemment, il me semble préférable de rédiger un bloc de commentaire conséquent précédent plusieurs lignes de code ou le corps d'une fonction/méthode complète. Dans le corps de la méthode, si on ne trouve que quelques lignes de commentaire ligne à ligne voire aucune ligne de commentaire, pourquoi pas, à condition que la documentation en en-tête de la méthode soit suffisante pour utiliser la méthode et qu'un bloc de commentaire en début du coprs de la méthode permette de comprendre la solution mise en oeuvre. Le tout en bon français (ou bon anglais...) et à jour.

Les optimisations locales d'un algorithme, la découverte d'un bug dans des couches basses corrigé localement sont des cas particuliers pour lesquels un commentaire ligne à ligne est justifié.

Enfin, mais il ne s'agit que de mon expérience, n'ayant travaillé à ce jour que sur des forfaits, demander aux intervenants de commenter le code a posteriori est économiquement infaisable et ne présente aucun intérêt pour le forfait si ce n'est obtenir un bon ratio lignes de commentaire/lignes de code (ratio au combien dénué de sens).

Pourquoi ? Parce qu'il ne reste jamais assez de temps en fin de projet pour commenter la doc, on préfère optimiser, paufiner, passer du temps en validation/qualification et autres métrologies.

Et tout cela nous ramène au sacro-saint principe qui est qu'il faut réfléchir avant de faire. D'un point de vue cognitif, notre processus de réflexion est boosté par le fait que l'on verbalise le problème et la construction de la solution. Penser la solution et l'écrire simultannément permet d'obtenir plus rapidement une solution viable voire optimale.

Un bon exercice : demandez à un concepteur de trouver une solution à un problème sans rédiger une ligne de code. Une fois la solution trouvée, demandez-lui de l'expliquer au reste de l'équipe et débattez de la solution. Vous serez surpris du nombre de fois où ce procédé vous aura permis d'obtenir quasiment l'implémentation finale et optimisée du code du premier coup. Ca coute du temps ? Oui, mais seulement a première vue. A l'usage vous vous rendrez compte du gain de cette solution : gain immédiat car vous évitez l'implémentation d'une mauvaise solution et de corrections succesives, et gain à long terme puisque la solution est mieux pensée et partagée par toute l'équipe.

Dans un projet où le temps est compté, la documentation se construit en deux temps, mais jamais a posteriori (dans l'idéal hein bien sûr) :
1- pendant la phase de spécification précédent les développemnts (ou, et c'est le plus fréquent, pendant les temps de spécification lorsque l'on effectue des spécifications en continue en parrallèle des développements)
2- pendant le développement

En 1, se construit la documentation la plus fournie, ce qui justifie les développements à venir. De nombreux outils Rose, Together, AMC... permettent de saisir cette documentation qui sera intégrée aux squelettes de code générés et servira de base à la documentation électronique ou papier générée par des javadocs, xdoclets, oxygen ou autres.

En 2, on vient compléter la documentation par des vrais commentaires qui mettent l'accent sur un point de détail localisé ou traitent de sujets liés à l'implémentation qui ne peuvent être appréhendées en conception.

Bien sûr, et c'est tout le problème, des efforts importants et une grande rigueur (et donc une part de budget importante dans le projet) sont nécessaires pour maintenir une documentation à jour (il y a souvent des itérations entre la doc et le code).

La documentation est trop souvent négligée du fait de son impact sur le coût financier des projets, ou du manque d'intérêt des informaticiens pour l'exercice de la prose. Mais comme disait Coluche, "ce n'est pas parce que la majorité à tort qu'elle a raison".

:: Fil rss des commentaires de ce billet ::

Architecture logicielle & Développement