Discussion :

[hegros]

Ensuite, il y a tout le problème de la rétention d'information, bref toute la partie humaine de la programmation. J'irais plus loin, c'est le problème de la transmission du savoir, on le voit dans notre société actuelle, et je suis sûr que dans dix ans on payera très cher avec les départs des anciens (formés à la vieille école ...).

Oui c'est ce que j'évoquais aussi plus haut, les commentaires se veulent tendre vers un objectif de knownledge (transmission du savoir) à l'écrit plus je disais qu'une séance de conception avec une équipe de programmation est plus knownledgable (désolé pour le terme) que l'écriture d'un commentaire.

Parce que allez comprendre le commentaire d'un ancien de 30ans de métiers qui a laissé un code que vous devez maintenir et faire évoluer par la suite. La transmission orale me semble tout aussi nécessaire et c'est ce qui manque le plus je trouve au final.

[koala01]

Ce n'est même pas le problème de la double compétence...

Lorsque j'étais ambulancier, j'étais (ainsi toutes les personnes qui travaillaient avec moi) formé à utiliser des termes médicaux, dont infarctus du myocarde est loin d'être le plus compliqué.

Mais, lorsque nous parlions de "personne bloquée", nous faisions référence à un état bien précis, tout à fait différent de "personne coincée", tous deux nécessitant l'intervention du SAMU mais pour des causes tout à fait différentes (et ce n'est encore qu'un exemple vite fait )

Le fait est que nous devions régulièrement transmettre des informations à d'autres services, qui utilisaient exactement les mêmes termes que nous pour représenter les mêmes choses...

Mais, si, à un seul moment, l'une des personnes qui devait transmettre une information venait à la modifier ne serait-ce que légèrement parce qu'elle l'avait interprété, nous étions tous dans la panade, en croyant partir sur quelque chose d'erroné...

Ici, nous sommes dans le même cas:

Deux "bons" programmeurs peuvent avoir des sensibilités différentes et interpréter un même code de manière malgré tout différente (surtout si l'un ou l'autre ne connait pas l'algorithme mis en oeuvre ou n'est pas au courent du fait qu'une situation particulière fait qu'il faut utiliser les indices compris entre 1 et N au lieu des indices entre 0 et N-1)

Et même sans aller jusqu'au point d'avoir plusieurs programmeurs, il faut te dire qu'il y a 365 jours dans l'année et 7 jours dans la semaine, qui sont autant de possibilités de faire autre chose et d'oublier les raisons qui t'ont poussé à écrire un code particulier.

Et, si, pour une raison ou une autre, tu dois revenir sur un code après un certain temps (mettons trois mois, ou plus), tu as de fortes chances d'avoir eu l'occasion d'oublier certains points de ton code, et certaines raisons qui t'on fait l'écrire de cette manière...

Une même cause ayant les mêmes effets, si tu n'a pas pris la peine de mettre des "jalons explicatifs" dans ton code, tu risque de prendre des décisions de modifications qui seront mauvaises

[chaplin]

Deux "bons" programmeurs peuvent avoir des sensibilités différentes et interpréter un même code de manière malgré tout différente

On est dans le subjectif, quand j'ai un doute sur un commentaire, je pose la question aux membres de l'équipe et si je peux je cherche a rentrer en relation avec les gens du métier pour comprendre l'objectif métier du code, quand c'est possible .

Parce que allez comprendre le commentaire d'un ancien de 30ans de métiers qui a laissé un code que vous devez maintenir et faire évoluer par la suite. La transmission orale me semble tout aussi nécessaire et c'est ce qui manque le plus je trouve au final.

Je pensais aux anciens qu'on pousse à la porte pour des raisons de pouvoir sans vouloir un instant profiter de leur savoir faire, mais ce que tu dis élargit le point de vue.

[hegros]

On est dans le subjectif, quand j'ai un doute sur un commentaire, je pose la question aux membres de l'équipe et si je peux je cherche a rentrer en relation avec les gens du métier pour comprendre l'objectif métier du code, quand c'est possible .

Oui mais là encore cela va perturber le process puisqu'il va falloir que la personne qui a écrit le commentaire soit disponible puis aussi qu'elle se souvienne ce qu'elle voulait expliquer...Les gens du métiers te répondront probablement que c'est à toi de te débrouiller sans eux

Tout cela pourrait être évité si ce commentaire n'était pas écrit finalement

[chaplin]

Les gens du métiers te répondront probablement que c'est à toi de te débrouiller sans eux

Comme le médecin qui dit à l'infirmière, vous préparez la dose habituel au patient. Tout est dans le subjectif ou plutôt l'interpretation, idem avec le crash d'airbus et je ne sais plus quel satellite voir la première fusée Arianne 5, etc ...

[gl]

Oui mais là encore cela va perturber le process puisqu'il va falloir que la personne qui a écrit le commentaire soit disponible puis aussi qu'elle se souvienne ce qu'elle voulait expliquer...Les gens du métiers te répondront probablement que c'est à toi de te débrouiller sans eux

Tout cela pourrait être évité si ce commentaire n'était pas écrit finalement

Si le commentaire a été écrit c'est que le code sous-jacent n'était pas trivial à comprendre ou que le fonctionnel à conditionné un choix à priori suspect. De ce fait, sans commentaire la même démarche (aller voir l'auteur original ou quelqu'un de fonctionnel) aurait été nécessaire.

Dans le cas contraire, oui c'est un commentaire inutile qui n'aurait pas du être là.


PS: travailler dans une entreprise où les autres développeurs te laissent avec tes problèmes et où les gens du métier ne veulent pas jouer leur rôle de référents fonctionnels, ce n'est pas vraiment !ma conception du travail et je doute que je resterait longtemps dans cette entreprise (essentiellement à cause du second point d'ailleurs, si c'est à moi à me débrouiller sans eux pour les problèmes concernant leur métier, ils doivent bien pouvoir se débrouiller sans moi pour les logiciels dont ils ont besoin=.

[hegros]

PS: travailler dans une entreprise où les autres développeurs te laissent avec tes problèmes et où les gens du métier ne veulent pas jouer leur rôle de référents fonctionnels, ce n'est pas vraiment !ma conception du travail et je doute que je resterait longtemps dans cette entreprise (essentiellement à cause du second point d'ailleurs, si c'est à moi à me débrouiller sans eux pour les problèmes concernant leur métier, ils doivent bien pouvoir se débrouiller sans moi pour les logiciels dont ils ont besoin=.

quand cela est possible en effet car lorsque tu es développeur et que ton référent fonctionnel c'est ton chef de projet tu ne discutes pas vraiment voir pas du tout avec les fonctionnels du coup c'est spécifique aux contextes.

Les commentaires par rapport au code propre cela pourrait bien être minimes (probablement pas pour la maintenance?) et c'est probablement pas aujourd'hui ce qui serait le plus caractéristique d'un code pas propre au contraire même dans bien des cas.

[gl]

quand cela est possible en effet car lorsque tu es développeur et que ton référent fonctionnel c'est ton chef de projet tu ne discutes pas vraiment voir pas du tout avec les fonctionnels du coup c'est spécifique aux contextes.

Non tu ne discutes pas directement avec les fonctionnels. Mais tu poses la questions au chef de projet qui y répond ou qui fait remonté aux fonctionnels selon le cas. Ce mode de fonctionnement ne me pose pas de problème non plus.

Ce qui me gênait dans la situation que tu avais décrite, c'est que je ne voyais aucune façon de valider un point fonctionnel. Si un cheminement existe, qu'il soit direct ou non, il n'y a plus de problème, tu peux toujours avoir les réponses nécessaires.

Les commentaires par rapport au code propre cela pourrait bien être minimes (probablement pas pour la maintenance?) et c'est probablement pas aujourd'hui ce qui serait le plus caractéristique d'un code pas propre au contraire même dans bien des cas.

Oui, ça pourrait être minime ou pas en fonction du contexte.



En fait en relisant les derniers échanges, j'ai l'impression qu'il y a un malentendu. Je n'ai peut être pas été très clair à ce sujet, mais mon propos n'est pas de mettre le plus de commentaires possibles, d'avoir 1/3 de commentaires (ou tout autre fraction d'ailleurs), de commenter chaque ligne de code ou de commenter pour le plaisir de commenter.

Mon propos est de mettre des commentaires lorsque cela est utile et efficace. Et si au final dans un cas il y a plus de commentaires que de code et ben tant pis ce n'est pas grave. Tout comme ce n'est pas grave, bien au contraire, s'il n'y a pas de commentaire lorsque ce n'est pas utile.

En fait je trouve aberrante la position qui consiste à bannir absolument tout les commentaires, tout comme je trouve aberrante celle qui consiste à imposer un pourcentage de commentaire.

Le gros problème reste bien entendu de savoir ce qui est utile. Sachant que ce qui semble inutile à un développeur pourra être utile au mainteneur, au re-lecteur, à l'utilisateur, au formateur ou autre.

[koala01]

Je suis parfaitement d'accord avec gl (encore une fois)...

Mon propos était peut être vague sur ce point, mais, lorsque je parlais de placer des commentaires pour s'assurer que tout lecteur à qui le commentaire peut s'adresser interprète le code (ou la partie de code) de la même manière, il me semblait évident (mais c'est ma "sensibilité" personnelle qui m'a fait penser ainsi ) que je parlais de commentaires qui apportent une réelle "plus value" du point de vue de la compréhension par rapport au code...

Il me semblait avoir été bien clair sur le fait que je parlais des commentaires cohérents et utiles ou nécessaires à la compréhension correcte du code.

A ce titre, je n'ai aucun problème à trouver dix lignes de commentaires cohérents et nécessaires pour comprendre une ligne de code, même si ce doit être redondant, mais j'ai horreur de n'avoir ne serait-ce que trois mots de commentaires qui n'apportent strictement rien à la compréhension du code

Les exemples que je donnais concernant le mauvais passage de l'information sont très clairement des cas extrêmes qui ont pour but d'en montrer les risques.

Mais, une chose est sûre, il faut veiller à ce que l'information passe correctement au minimum au sein d'une équipe, et, idéalement, entre les différentes équipes / intervenants, quelle que soit la fonction de l'intervenant ou le chemin parcouru par l'information pour arriver à la personne / à l'équipe concernée.

Dans ce cas, le meilleur moyen et la meilleure place pour assurer le bon passage d'informations particulières, utiles et cohérentes qui ne trouvent pas forcément leur place dans les autres documentations (je reviens avec le problème de l'index numéroté à partir de 1, car c'est le cas le plus flagrant), c'est de passer par un commentaire avant la première ligne de code "tendancieuse"...

Ce commentaire peut être minimal, et proche de

Code C++ :

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

/* !!! La numérotation de l'index va de 1 à N et non de 0 à N-1 !!! */

C'est simple et efficace, et toute personne posant les yeux sur le code comprendra clairement les raisons qui font que la boucle est de l'ordre de for(i=1;i<=N;++i)

[gl]

Ce commentaire peut être minimal, et proche de

Code C++ :

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

/* !!! La numérotation de l'index va de 1 à N et non de 0 à N-1 !!! */

C'est simple et efficace, et toute personne posant les yeux sur le code comprendra clairement les raisons qui font que la boucle est de l'ordre de for(i=1;i<=N;++i)

A titre personnel, j'aurais tendance à rajouter la raison pour laquelle ce choix a été fait (par exemple "du fait du fonctionnement de la bibliotheque XXXX") afin de penser à revenir à un code plus idiomatique le jour où la raison n'existe plus (le commentaire disparaissant à ce moment là bien entendu). Mais c'est de l'ordre du détail.

[hegros]

koala1 c'est utile pour qui ce commentaire quelqu'un qui a 10 ans de métiers dans le langage qui utilise cette convention ? en tout cas je comprends mieux notre désaccord sur certain point

il y a tellement de typologie de commentaire en même temps pour s'y retrouver...

[koala01]

A titre personnel, j'aurais tendance à rajouter la raison pour laquelle ce choix a été fait (par exemple "du fait du fonctionnement de la bibliotheque XXXX") afin de penser à revenir à un code plus idiomatique le jour où la raison n'existe plus (le commentaire disparaissant à ce moment là bien entendu). Mais c'est de l'ordre du détail.

Effectivement, ce serait encore mieux

koala1 c'est utile pour qui ce commentaire quelqu'un qui a 10 ans de métiers dans le langage qui utilise cette convention ? en tout cas je comprends mieux notre désaccord sur certain point

C'est utile pour toute personne qui accepte l'idée d'avoir eu l'occasion d'oublier un code (qu'il a éventuellement écrit) entre deux moments (parfois fort espacés) où il pose les yeux dessus...

il y a tellement de typologie de commentaire en même temps pour s'y retrouver...

Comme je l'ai déjà fait valoir, un code est plus souvent lu / étudié qu'il n'est écrit / compilé, et les raisons de ne pas (ou plus) savoir ce que fait le code, pourquoi il le fait de cette manière ou la manière dont il s'organise (les fonctions qui l'appellent ou que le code appelle) et le pourquoi des appels sont nombreuses et variées.

Si, à chaque fois que l'on croise un code "inconnu" (ou oublié), il faut passer 20 minutes à étudier le code sous toutes les coutures pour arriver à le comprendre, cela fait 20 minutes de perdues inutilement.

Le pire de l'histoire, c'est que si tu reprend ce code trois mois plus tard, tu perdra à nouveau 20 minutes à l'étudier pour le comprendre, et, que si ton collègue essaye de le lire juste après toi, il perdra également 20 minutes à l'étudier pour le comprendre...

Quand on pense qu'un commentaire clair, justifié et cohérent t'aurait sans doute permis de comprendre "quasi instantanément" ce que fait le code ou pourquoi il le fait, n'aurait pris que quelques secondes ou quelques minutes à être écrit, on se rend compte du gain de temps (donc de productivité) qu'il induit...

Ceci dit, je voudrais rajouter pour les détracteurs des commentaires, que, si ne serait-ce qu'un seul de vous peut honnêtement me jurer n'avoir jamais passé, en 5 à 10 ans d d'expérience, ne serait-ce que 10 minutes à se "gratter la tête" devant un code non commenté, écrit par lui quelque mois plus tôt ou par un tiers n'importe quand, en se demandant ce qu'il faisait ou la raison pour laquelle il le fait de cette manière, je serai prêt a admettre l'inutilité des commentaires.

[gl]

koala1 c'est utile pour qui ce commentaire quelqu'un qui a 10 ans de métiers dans le langage qui utilise cette convention ? en tout cas je comprends mieux notre désaccord sur certain point

Je pense qu'il y a un point que tu n'as pas vu dans l'exemple de koala01. Il s'agit d'un commentaire indiquant qu'on utilise exceptionnellement une convention (index de 1 à N) dans un langage où la convention est justement différente (index de 0 à N-1). Donc oui ce commentaire peut être utile à quelqu'un ayant 10 ans d'expérience dans ce langage.

Lorsque l'on utilise la convention naturelle du langage, il est bien entendu totalement inutile de le commenter.

[hegros]

Oui certe c'est vu gl, c'est une spécification technique à mon sens ce n'est pas un simple commentaire il n'explique rien il spécifie soit sa place dans le code source est à mon avis discutable.

en même temps une spécification technique sur une ligne on ne demande pas mieux avant de coder alors oui par rapport aux autres commentaires il est utile bien que le coup de la convention marque une typologie de commentaire les spécifications techniques.

[koala01]

Cet exemple de commentaire justifie (quitte à ne pas préciser les raisons particulières qui font que) que tu écrive un code qui, a priori, pourrait sembler incorrect, et, pour lequel tu n'a, a priori, aucun autre moyen d'avoir la justification...

Mais il permettra à la personne qui posera les yeux sur le code (et ce peut être toi, dans trois mois) de se rendre compte que le code a priori incorrect est, malgré tout justifié, et donc, évitera à cette personne, en programmeur consciencieux, de modifier (indument) le code pour le rendre conforme à la convention habituelle, le tout, en lui évitant 20 minutes de recherches (parfois hardues) dans les specs ou la documentation...

D'autant plus que le fait qu'une fonction va utiliser une convention pour les indexes différentes de celle habituellement utilisée peut ne représenter qu'une ou deux ligne(s) dans une documentation ou un document de spécifications de plusieurs dizaines (voire centaines) de page...

A moins de savoir quelle fonction agit de la sorte (et comment le savoir sans passer par un commentaire ) la recherche de ce "pourquoi" revient donc à rechercher une aiguille dans une meule de foin

Ce commentaire va prendre quelques secondes à peine à être écrit (et, comme je l'ai admis, l'idéal serait de rajouter que c'est du fait de la fonction machin de la bibliothèque truc) mais assurera la transmission correcte d'une information importante pour la compréhension et la maintenance du code.

Évidemment, comme l'a fait remarquer gl, si lafonction machin de la bibliothèque truc est un jour modifiée pour respecter la convention habituelle, le commentaire devra être supprimé et le code adapté

[hegros]

bon il faudrait zapper la partie commentaire de ce débat le tour a bien été fait parce que ton exemple non franchement il fait peur et les explications aussi....

[koala01]

Hé bien, recentrons le débat sur le thème de la discussion...

Pour moi, un code "propre", c'est un code qui me permet de comprendre "relativement facilement" ce qu'il est sensé faire, pourquoi et comment il le fait lorsque je pose les yeux dessus...

Je crois que, dans l'ensemble, nous sommes relativement d'accord sur cette définition, même si elle est, effectivement très générale

Pour ce qui est du comment le code fait ce qu'il est sensé faire, le consensus semble aussi général pour dire que cela passe par l'utilisation de noms "auto commentés" et une mise en forme cohérente.

Là où nous ne sommes peut être plus tout à fait d'accord, c'est sur ce qui permet de comprendre ce que le code est sensé faire, le pourqoi et la notion de "relativement facilement"...

Pour moi, "relativement facilement" veut dire que je ne dois pas être obligé de parcourir l'ensemble des documents à ma disposition (documents d'analyse ou de conception, documentation utilisateur ou specifications, gestionnaire de gestion et de remontée de bug, voire, documentation sur le web ou le "post it" sur l'écran de mon voisin) avant d'être en mesure de comprendre ce qu'est sensée faire une fonction particulière qui représente, en terme de volume dans les documents dont je dispose, à peine plus que ce que peut représenter une aiguille dans une meule de foin...

Parce que, si je dois passer 5 heures à lire consciencieusement tous ces documents pour m'imprégner (ou me rappeler) de tous les tenants et aboutissants du projet alors qu'il ne s'agit peut être que d'apporter d'une modification qui pourrait me prendre à peine quelques minutes, j'estime que c'est une sérieuse perte de temps tout à fait inutile et que le temps perdu aurait surement pu être utilisé à des fins autrement plus productives...

Bien sûr, je laisse tout le monde penser autrement, mais je ne serais pas étonné que cette analyse fasse malgré tout elle-aussi consensus...

Le gros problème, selon moi, c'est que le code seul ne suffit pas à fournir ce genre d'informations...

C'est la raison pour laquelle je plaide en faveur de la présence de commentaires (utiles et cohérents) suffisants pour me permettre de retrouver les informations utiles au besoin.

On me reprochera sans doute la redondance avec les différents documents qui sont (sensés être) à ma disposition...

Sans aucun doute...

Mais, à bien y penser, la redondance des informations est la caractéristique même des différents documents:

• Les cas d'utilisation ne sont qu'une approche différente des besoins à remplir
• les diagrammes de classes, d'appel ou de collaboration (et tous les autres) n'ont pour seul et unique but de préciser comment les cas d'utilisation peuvent être mis en oeuvre, et, partant, sont redondants avec l'analyse des besoins
• Même les spécifications sont redondantes: avec les spécifications globales de la société (redondance d'un projet à l'autre) et avec certains besoins propres au projet.
• Et, à bien y réfléchir, la documentation utilisateur l'est tout autant en indiquant à l'utilisateur la manière dont ses besoins ont été pris en compte.

Dés lors, pourquoi devrait on accepter une redondance pour l'ensemble du processus sauf pour ce qui fera s'arracher le plus de cheveux des programmeurs: le code qui met tout cela en oeuvre

Si, en tant que chef de projet, tu estimes cohérent d'attendre plusieurs heures qu'un membre de l'équipe s'imprègne de tous les tenants et aboutissants du projet pour apporter une modification, en étant sûr "de ne pas faire de connerie", juste pour "éviter des commentaires redondants", tant mieux pour toi...

Pour ma part, j'ai déjà exprimé mon avis

[Pierre Fauconnier]

Salut!

Pour ma part, j'adhère sans réserves à la synthèse de Koala01. Bravo pour ce résumé simple, concis et complet.

[hegros]

Il y a plusieurs écoles effectivement, des anciennes et des nouvelles chacun devrait trouver une place dans ce thread.

Bref, pour revenir au code propre pour ma part c'est revenir il y a 10 pages en arrière lorsqu'on évoqué les facteurs ISO de qualité (portabilité, robustesse,maintenabilité....) soit rien à voir avec les commentaires du coup parce que comme on l'a vu cela ne sert ni à la robustesse ni à la maintenabilité ni à la portabilité etc...

[koala01]

Bref, pour revenir au code propre pour ma part c'est revenir il y a 10 pages en arrière lorsqu'on évoqué les facteurs ISO de qualité (portabilité, robustesse,maintenabilité....) soit rien à voir avec les commentaires du coup parce que comme on l'a vu cela ne sert ni à la robustesse ni à la maintenabilité ni à la portabilité etc...

Et c'est là dessus que nous ne sommes pas d'accord...

Je suis d'accord qu'un commentaire n'ajoute rien à la robustesse d'un code, mais, du point de vue de la maintenabilité, et, dans une certaine mesure, même de la portabilité d'un code, j'estimes que cela apporte énormément...

J'ai l'impression que tu pars du principe que toute personne qui devra poser les yeux sur un code source connaitra le projet "sur le bout des doigts" et maitrisera parfaitement le "sujet" du projet...

Si c'est effectivement le cas, alors, oui, on peut effectivement estimer que les commentaires n'apporteront rien en terme de maintenabilité du code. Sauf que...

Sauf qu'un code source est un document qui, au même titre que tous les documents d'analyse et de conception (ou de documentation utilisateur) sert à permettre le passage d'informations.

Et que le destinataire principal n'est pas le "système automatique" qui devra gérer ce code (comprend: le compilateur ou l'interpréteur, pour les plus importants) mais... la personne qui devra, à un moment donné, poser les yeux sur le code, pour l'étudier ou pour le modifier.

En effet, le compilateur ou l'interpréteur sont des systèmes très "carrés" qui te feront rapidement savoir s'il ne comprennent pas ce que tu leur demande de faire.

Revers de la médaille, si tu leur demande, d'une manière qu'il comprennent, de faire une connerie, ils la feront sans s'inquiéter de savoir si ce que tu leur demande de faire est opportun ou si c'est une connerie

C'est pourquoi, le destinataire principal du code source est en réalité, au même titre que tous les autres documents, celui qui... posera les yeux dessus...

Tu peux donc partir du principe que chaque employé de la boite maitrise suffisemment le langage, chaque projet et les "sujets" de chaque projet pour te dire que les commentaires seraient inutiles...

Mais il arrivera toujours un jour où il y aura une modification "urgente" à apporter et où la seule personne disponible pour y travailler sera le "pauvre" stagiaire qui est débarqué dans l'entreprise depuis deux jours, qui ne connait encore des bâtiments que son bureau, les toilettes et la cafétaria, qui ne connait du langage que ce qu'il a pu apprendre sur les trente heures de cours qui y étaient consacrées, qui n'a travaillé la veille que sur un projet tout à fait différent et qui ne maitrise absoluement pas ni le projet qu'on lui demande de vérifier ni le sujet de ce projet...

C'est caricatural, je te l'accorde, mais ca risque malgré tout de n'être pas si loin que ca de la vérité (ce peut très bien être quelqu'un de très expériementé, maitrisant parfaitement le langage mais ne sachant rien du projet ni du sujet du projet )

Si tu te contente de lui mettre entre les mains les 900 pages de documents relatifs à ce projet et de lui dire qu'il y a un porblème à résoudre dans telle ou telle fonction, je lui promet bien du plaisir pour arriver à y apporter une solution, même si tous les noms utilisés par et dans la fonction sont correctement auto-commenté

Et le malheur est que Murphy et consors veilleront à ce que cela arrive un jour ou l'autre