Discussion :

[Matthieu Vergne]

Ce qui revient au problème "expliciter ou ne pas expliciter", qui est un autre problème. Évidemment, il est important de fournir autant d'information que nécessaire, mais après on entre dans d'autres débats, comme le fait que tout expliciter revient à fournir une quantité incommensurable d'information (potentiellement infinie), et même en restant dans des proportions humainement faisable, on peut faire face au problème de surcharge (tellement de choses à retenir qu'on en oublie la majeure partie ou ne sait plus quoi considérer), etc.

Certes, c'est important, mais moi je le vois comme un autre débat.

[CodeurPlusPlus]

Récemment j'ai traqué un BUG banal (j'avais confondu deux variables) pendant dix heures... Le fait est que les deux variables avaient des noms très proches et assez peu explicites (trop "génériques"), et que j'avais introduit le BUG en refactorant assez sauvagement une grosse section de programme, refactorisation pendant laquelle il était facile, au milieu de milliers d'autres opérations, de confondre ces deux variables. La recherche de l'erreur a été très longue, car j'ai fort logiquement suspecté -- à tort -- que c'était la refactorisation qui était la cause du problème : sans doute étais-je passé à côté d'un vilain effet de bord...

Si les deux noms avaient été dès le départ suffisamment différents, ce n'est pas que j'aurais trouvé l'erreur plus vite... c'est carrément que je ne l'aurais même pas commise !

On n'insistera donc jamais trop sur le fait de bien choisir ses identifiants... et sur le fait qu'il est bienvenu, à chaque fois que c'est possible, de supprimer un commentaire à vocation "explicative", quitte à réécrire avec des identifiants mieux choisis pour que le code reste clair...

Après, il y a des commentaires qui restent quoi que l'on fasse... c'est le cas de ceux donnant des infos qui devraient en réalité plutôt se trouver dans la documentation... je dirais qu'il vaut mieux éviter d'en écrire trop, ou du moins d'en laisser trop... mais parfois on peut trouver une bonne raison d'en écrire un.

Il y a aussi d'innombrables situations dans lesquelles certains commentaires sont utiles dans du code pas encore finalisé, notamment pour simplifier le travail d'équipe... à condition de se mettre d'accord sur le fonctionnement de la chose : par exemple le statut d'un tel commentaire doit être clair (il a vocation à disparaître une fois telle ou telle étape franchie); ou bien alors "la responsabilité de virer le commentaire revient à celui qui l'a écrit, il doit donc y penser, etc". D'où l'idée de faire de temps en temps une traque systématique aux commentaires plus ou moins obsolètes.

Il arrive aussi qu'on ne commente pas suffisamment...
et là j'ai une stratégie très simple (qui ne se suffit pas à elle seule mais qui aide) :

quand je me ressers d'un ancien module, je n'ai évidemment plus l'existence de toutes les fonctions en tête, et encore moins leurs rôles respectifs... donc, je regarde la liste des prototypes des fonctions (quand je programme en C elles sont tout simplement dans le .h ou dans une section spécifique du .c pour les fonctions pseudo-"privées"). Normalement, c'est à dire en théorie, rien qu'en lisant le prototype d'une fonction je dois être capable de comprendre ce qu'elle fait, notamment au niveau d'éventuels effets de bord bien sournois. Mais parfois, en pratique, en lisant le prototype, je ne suis pas tout à fait sûr des effets de bord de la fonction, ou bien de la façon dont on l'utilise... même, dans certains rares cas, je ne sais plus à quoi elle sert. Quand cela se produit, je suis obligé de consulter le code de la fonction. Une fois que c'est fait, une fois que j'ai les réponses aux questions que je me posais, je reviens dans le .h et j'ajoute un commentaire de sorte à ne pas être à nouveau obligé d'aller regarder le .c à l'avenir.


Au sujet de la maintenabilité d'un logiciel (on s'écarte certes du sujet précis que sont les commentaires), voici exposée en vidéo une petite subtilité qui s'est imposée à moi comme, finalement, une évidence :

C'est que la notion de "lisibilité" du code, qu'on ressort tout le temps dans toutes nos discussions, notamment quand on se tape dessus pour savoir ce qui fait ou non un bon commentaire, est en réalité une notion floue et éventuellement trompeuse. Un code a priori moche peut être très maintenable et inversement...

Et pour les masochistes (ou ceux qui n'ont rien d'autre à faire) :

Suivre cette vidéo-ci avant celle dont j'ai donné le lien plus haut rend la démonstration beaucoup plus convaincante AMHA... mais six fois plus longue... faut être masochiste je vous dis.

[marc.guillemin]

Programming is the art of telling another human being what one wants the computer to do.
-Donald Knuth

[Luc Hermitte]

Sur notre sujet des commentaires, je viens de tomber sur ce billet écrit il y a peu: https://akrzemi1.wordpress.com/2015/...comment-style/

[Matthieu Vergne]

Sur notre sujet des commentaires, je viens de tomber sur ce billet écrit il y a peu: https://akrzemi1.wordpress.com/2015/...comment-style/

Pour moi, c'est un mauvais exemple. Recopiant et traduisant ce que j'ai commenté là bas : je préfèrerai renommer la fonction c.go() qui ne veut pas dire grand chose ou, si c'est impossible parce que son auteur a ses raisons, ajouter une fonction init_devices() bien plus explicite et y mettre ton c.go(), puis utiliser cette méthode bien plus explicite à la place. Pas besoin de commentaire, l'auteur original n'a pas à blesser son ego en renommant son... hum... truc, et le compilateur peut gérer l'optimisation pour remplacer l'appel à la nouvelle fonction par son contenu, comme si de rien n'était. Éventuellement, documenter cette nouvelle fonction de manière plus complète que le commentaire.

[Luc Hermitte]

Je suis d'accord qu'un meilleur nom est préférable -- quand on en a la possibilité (ce n'est pas toujours le cas avec COTS et FSOSS).

L'auteur présente une bidouille (et ce n'est rien d'autre: un dirty hack) qui a pour vocation de corriger les cas de commentaires qui se restent derrière après refactorisations -- la bidouille ne peut rien pour les cas d'obsolescence lorsque le rôle de la variable change. Je ne sais encore trop quoi en penser. Je tends toujours, pour l'instant, dans le camp des : "moins il y a des commentaires dans le code mieux c'est ; et si le code n'est pas compréhensible, c'est qu'il est mauvais et à reprendre." Mais je note le "il y a un moyen de gérer une partie des reproches faits aux commentaires qui trainent dans le code".

[Matthieu Vergne]

Hum... tu peux préciser tes acronymes COTS/FSOSS ? Je suis pas sûr d'avoir les bons.

[Luc Hermitte]

En gros je faisais référence à des bibliothèques/composants tiers, qu'ils soient d'origine commerciale (Commercial Off-the-Shelf), ou libre/OSS (FreeSoftware/OpenSourceSoftware -- et je vois, au temps pour moi, que le bon acronyme est FSOS).

Si les noms des fonctions de leur API sont mal nommés, ou s'il y a des rituels d'initialisation à respecter, on aura beau avoir une fonction encapsulante chez nous avec un joli nom, à l'intérieur de cette fonction si on se rend compte que l'on avait mal employé l'API tierce et que l'on corrige le code, il reste toujours un risque que les commentaires ne suivent pas.

[Matthieu Vergne]

A priori, Open Source Software c'est bien OSS. Tout du moins je me rappelle pas l'avoir vu autrement et ça correspond aux acronymes que j'ai trouvé. J'avais juste pas compris pourquoi tu mentionnais ça.

[Nebulix]

... j'ai tendance a coder en ecrivant sous forme de commentaires ce que j'ai a faire puis a completer ...

Tout à fait d'accord. Les commentaires utiles sont ceux qu'on écrit AVANT de coder.

[Cyrilange]

Entièrement d'accord !

[Matthieu Vergne]

Tout à fait d'accord. Les commentaires utiles sont ceux qu'on écrit AVANT de coder.

Sauf que ce dont il parle ("ecrivant sous forme de commentaires ce que j'ai a faire puis a completer") est probablement de commentaires que tu auras toutes les raisons de retirer APRES avoir codé. Et cela pour la simple raison que ça ne fait que représenter ta conception actuelle, qui sera alors traduite sous forme de code bel et bien opérationnel. Si ta conception est foireuse, le code le sera aussi, or c'est celui-ci qui sera corrigé, pas forcément le commentaire, qui viendra alors ajouter à la confusion en étant obsolète : quelqu'un qui arrive après et qui vois qu'il faut encore corriger le code, mais vois que le code ne correspond plus aux commentaires, se dira très vite "ah ben oui, s'il fait pas correctement ce qu'il est censé faire aussi..." et aura tôt fait de "corriger" le code pour respecter les commentaires, ce qui avec un peu de malchance corrigera effectivement son bug, mais réintroduira le bug précédent.

Par contre, si tu parles de documentations, là je suis tout à fait d'accord. Mais l'objectif n'est pas de dire comment la fonction est codé, mais pour quoi faire. Ta documentation établit ton cahier des charges pour la fonction concernée.

[Cédric Doucet]

Bonjour,

c'est un faux problème et/ou une mauvaise exégèse des livres mentionnés.
Ces livres ne prônent pas du tout l'arrêt des commentaires.
Ils prônent l'arrêt des commentaires redondants et des commentaires palliatifs à l'aide d'un nommage correct des variables et fonctions.

Dans l'exemple suivant, le commentaire est redondant :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
// return the size 
int size();

C'est typiquement le genre de commentaire qu'on peut trouver dans les codes auto-documentés à l'aide de générateurs comme doxygen, javadoc, docstring, etc.

Dans l'exemple ci-dessous, le commentaire est palliatif :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
// print working directory
void pwd();

Il aurait été tout aussi efficace de supprimer le commentaire et de renommer la fonction :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
void printWorkingDirectory();

De manière générale, il faut éviter les abréviations.
Toutefois, il existe des domaines dans lesquelles certaines abréviations sont consacrées.
Dans ces cas particuliers, tenter de mieux nommer la variable pourrait presque nuire à la lisibilité du code.
La manière dont on nomme les variables dépend du contexte.
Dans certains contextes, conserver le nom pwd plutôt que PrintWorkingDirectory pourrait se justifier.
Mais dans les deux cas, le commentaire reste redondant et inutile.

En dehors de ces commentaires, il en existe beaucoup d'autres qui sont utiles.
Par exemple, le commentaire ci-dessous :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
// Warning: this singleton class is not designed to work in a concurrent programming environment 
class Singleton
{
   // implementation details
}

Bref, il n'a jamais été question de supprimer les commentaires.
Il s'agit de rendre les codes plus lisibles :
- en nommant mieux les variables et les fonctions
- en supprimant les commentaires inutiles qui nuisent à la lecture (parcours vertical des yeux)

L'idée fausse qu'il faut supprimer tous les commentaires est malheureusement propagée par certains acteurs de la mouvance agile qui retiennent uniquement que "la documentation c'est le code".

[elfasys]

Bonjour

Pour moi qui ne fait que des applications prototypes (et qui ait commencé la programmation avec des noms de 8 lettres majuscules + chiffres, maximum) une variable bien nommée est indispensable, non pas pour comprendre, mais pour comprendre facilement le code : peut-être est-ce ma mémoire qui fait des siennes, mais si je dois revenir dans un code un an après sa mise en fonction, je préfère relire du code avec des variables au noms explicites, et une programmation qui utilise le plus possible les fonctions de base qui existent dans tous les langages et que tout le monde connait.

Avec, en prime, des blocs de commentaires expliquant mes motivations, mes intentions, et les raisons de mes choix. En utilisant bien sûr un langage et des textes en français, puisque c'est ma langue maternelle...

Et, comme il s'agit toujours pour moi d'applications uniques, avec un gros problème de documentation (que va faire mon programme dans cette situation ?) je viens de découvrir récemment (si, si, au bout de 35 ans...) que certaines parties du code, si elles sont écrites selon ces règles, pouvaient être lues comme un texte explicatif directement par mon client (qui est tout de même un technicien).

Et s'il ne comprend pas, je n'en déduis pas que ma documentation n'est pas à jour, mais seulement que mon code est mal fait, et je corrige.

Mais ce qui est valable pour mes applications d'automatisme (un mix de langage d'automate et de code Windev) ne s'applique certainement pas à tous les cas.

Quoique j'ai pu comparer du code C++ écrit selon ces règles, et la même application par un autre programmeur écrite - on va dire autrement. Sans être familier de ce langage, je n'ai eu aucune difficulté à découvrir ce que je cherchais dans la première version (et à convaincre mon client de jeter la deuxième).

[foetus]

Personne n'a parlé du système de codetags / Fixme Comments

L'idée du truc, c'est d'avoir des mot-clefs qui puissent être cherchés/ trouvés par le codeur/ l'IDE - éditeur/ des logiciels externes pour être extraits/ surlignés - retenir l'attention.

Voici une petite partie:

• NOTE: Description of how the code works (when it isn't self evident).
• XXX: Warning about possible pitfalls, can be used as NOTE:XXX:.
• HACK: Not very well written or malformed code to circumvent a problem/bug. Should be used as HACK:FIXME:.
• FIXME: This works, sort of, but it could be done better. (usually code written in a hurry that needs rewriting).
• BUG: There is a problem here.
• TODO: No problem, but addtional code needs to be written, usually when you are skipping something.

Et Wiki, dit qu'on peut mettre une date ou d'autres informations comme ceci // TODO:2008-12-06:johnc: ....

Et moi je mets toujours XXX WARNING ou XXX TODO

[Matthieu Vergne]

Personne n'a parlé du système de codetags / Fixme Comments

Perso, mes commentaires se limitent quasiment à ça. Je fais généralement du code générique, donc self-contained et sans optimisation context-specific, du coup y'a pas de subtilité et donc pas besoin de commentaires si on fait un code lisible. Évidemment, aux exceptions près, qui sont très rares donc ça mérite d'être qualifié d'exception. Du coup, j'utilise les commentaires pour mettre mes todos et fixme, c'est tout ce que j'utilise. Tout le reste, c'est soit du code, soit de la doc.

[ChristianRoberge]

Effectivement, plus de 95% des commentaires d'un programme sont inutiles si on a une bonne nomenclature de noms. ceux qui disent que les noms ne représentent plus ce que fait réellement le code après un certain temps font de la mauvaise programmation, du mauvais design logiciel. Une chien ne peut devenir un chat même si ce 2 animaux à 4 pattes!
Pour ma part je maintiens 3 niveaux de commentaires:
1- Les variables, fonctions et autres ont toujours des noms auto explicatifs pour éviter au maximum l'utilisation de commentaire.
2- Les commentaires dans le code sont utilisés que dans le cas où la simple analyse du code ne suffit pas à comprendre les subtilités des actions que le programme réalise (inutile de dire qu'il sont très rare)
3- Renvoi à des fichiers de documentation. Il peut s'agir de lien internet, de description d'algorithme complexe et de design haut-niveau.

Mes expériences m'ont montré que c'est qui est le plus efficace pour passer et introduire de nouveaux programmeurs dans un équipe. C'est certainement critiquable car la documentation est souvent courte mais, je crois que c'est la plus performante compte tenu de l'évolution rapide de l'informatique. Passé trop de temps pour une belle documentation de haute qualité ne sert à rien si elle ne suit pas l'évolution du code.

[Matthieu Vergne]

Pour ma part, ce n'est pas la documentation qui doit suivre le code, sinon ça veut dire que ta documentation dit comment est implémenter la fonction, et elle est donc redondante avec ton code. C'est le code qui doit suivre la documentation, dans le sens où j'utilise la documentation comme cahier des charges pour la fonction. Si la documentation doit changer, c'est parce que les besoins ont changé, et seulement après on change le code pour suivre. Et encore, dans ce genre de cas, il faut se poser la question si on souhaite vraiment changer la fonction ou en créer une neuve, car cette fonction est censée être utilisée selon les anciens besoins. Une telle modification implique donc une revue du code partout où cette fonction est utilisée, et là encore la documentation des fonctions appelantes se contente de traduire les besoins qu'elles représentent, ce qui te permet de modifier le code sans toucher à la documentation et sans devoir revoir les fonctions appelantes des fonctions appelantes, etc.

Typiquement, en Java je fais les interfaces documentées, de manière à avoir une découpe nette entre la documentation et le code : la documentation est dans l'interface, qui ne contient donc aucun code puisque c'est une interface, et le code est dans les différentes implémentations, qui doivent donc toutes respecter ce que dit la doc.

[Jean GVE]

Je peux me considérer comme un vétéran de la programmation, ayant sévi en assembleur, en LTR, en C, (et aussi un peu de Fortran et aussi de Pascal), puis en ADA et en Cobol aujourd'hui j'interviens (encore) comme animateur de formation et analyste Cobol / PACBASE.
Je suis partisan de des 2 méthodes (sur des programmes nouveaux) on code directement en commentaire du langage algorithme du programme et quand on est content de soit, on commence à réaliser le programme dans le commentaire en utilisant un nommage intelligible (défini par des règles de codage)... La qualité peut être contrôlé par un analyseur statique et un programme d'extraction des commentaires permet de récupérer une partie de l'analyse détaillée (algo) qui devrait toujours être à jour même après 10 ans de maintenance... (Ça c'est un vœux pieux !).
Mais cette méthode n'est intéressante que pour des gros programmes, avec les méthodes objets cela peut être discutable du fait de la répartition des sources d'un programme dans une multitude de fichiers. Là ce n'est plus mon domaine... Je parts bientôt à la retraite.
JM
PS: L'algo est écrit en français, il n'y a pas de redondance puisse que tous les langages de programmation sont en "étasunien" commentaires en PDL (Program Design Language en langue du pays)

[autran]

Oui je suis en accord avec cette affirmation, et je vais même plus loin....
Je pense que le test unitaire est inutile. En effet le développeur doit savoir ce qu'il a écrit et pouvoir le débuguer facilement.
En outre les tests de recettes sont indispensables mais rarement mis en place par le client pourtant ce sont biens ces tests qui permettrait au développeur de faire du TDD.