Discussion :

[koala01]

Tout programmeur doit savoir commenter son programme.

Non, tout programmeur devrait savoir écrire du code lisible et compréhensible.

On peut bien sur discuter sur ce qui permet de rendre le code lisible, et cela dépendra fortement du langage que tu utiliseras, mais, si tu dois recourir aux commentaires pour atteindre cet objectif, c'est très clairement que tu es passé "à coté de quelque chose".
C'est obligatoire qu'il soit petit ou grand...
Pourquoi ? car l'on peut créer un petit programme en entreprise mais qui deviendra grand dans une entreprise ex: Hum un petit moteur d'un ERP et on rajoute des modules avec le cahier des charges et le cahier des charges augmente et l'on rajoute des modules ...
Vous tomber malade plouf sans commentaire ni documentation votre remplacent sera dans la panade...[/QUOTE]Dis moi, ton remplaçant, il aura plus facile à s'y retrouver face à des commentaires désynchronisés par rapport au code ou face à une absence pure et simple de commentaire

Si, pour apporter une modification ou pour résoudre un bug, ton remplaçant est confronté à des commentaires désynchronisés, devra-t-il

1. Te laisser un message te demandant de mettre tes commentaires à jour
2. Modifier le code (au risque de tout casser) pour que le code corresponde au commentaire
3. Modifier les commentaires pour qu'ils correspondent à la réalité du code (avec le risque de ne peut etre pas comprendre parfaitement ta logique)

Il faut le faire dès le début que ce soit un petit ou un grand programme.
Eclipse click projet créer Javadoc.

On a, très tôt dans cette discussion, fait la distinction entre les commentaire "de documentation" (les "cartouches" des classes et fonctions) et les commentaires dans le code.

On est tous d'accord (ou du moins la plupart sont d'accord) avec le fait que les cartouches ont leur utilité .

Par contre, les avis divergent quant à l'utilité de commentaires à l'intérieur du code (sans visée de documentation)

[BenoitM]

Amen
Est-ce que ça vaut toujours le coup ou c'est passer beaucoup de temps pour pas grand chose de plus (voire plus de problèmes) ?

Si tu passes beaucoup de temps à commenter ton code c'est qu'il est mal commenté
Si tu ne passes pas de temps à le commenter c'est qu'il est mal commenter

De plus je connais peu de programme bien écrit ( à part les miens biensur)

[koala01]

Si tu passes beaucoup de temps à commenter ton code c'est qu'il est mal commenté
Si tu ne passes pas de temps à le commenter c'est qu'il est mal commenter

De plus je connais peu de programme bien écrit ( à part les miens biensur)

Par expérience, les gens sont suffisamment fainéants que pour appliquer la loi du "moindre effort" lorsqu'ils essayent de comprendre un code.

C'est à dire que, s'ils ont le choix entre lire un texte qui décrit ce que le code est sensé faire et lire le code lui-même (ce que le code fait effectivement), ils vont forcément commencer par lire ce que le code est sensé faire et partir du principe que c'est ce que le code fait.

Ils risquent donc de perdre énormément de temps pour avoir passé un tronçon de code qu'ils estiment correct (sur base des commentaire) alors que l'erreur se trouve dans ce tronçon particulier, tout cela, pour finir tôt ou tard, n'ayant définitivement pas trouvé l'endroit où l'erreur se trouve, par revenir quand même sur le code lui-même et parfois trouver l'erreur en quelques secondes / minutes à peine.

Un code correctement écrit, avec des variables et des fonctions dont le nom est explicite, avec des fonctions n'ayant qu'une et une seule responsabilité, n'a a priori besoin d'aucun commentaire à partir du moment où l'on est en mesure de déterminer exactement le résultat que l'on est en droit d'attendre de la part de la fonction dans une situation donnée.

Pour être en mesure de déterminer ce résultat, le nom de la fonction (pour les plus simples) ou le cartouche (pour celles qui sont soumises à des pré ou post conditions) sont amplement suffisants.

Tout commentaire supplémentaire risque, tôt ou tard, de ne plus être représentatif de ce que fait effectivement le code, car celui qui corrige le code ne pensera que trop rarement à synchroniser les commentaires existants avec les modifications qu'il aura apportées.

C'est à ce moment là qu'il vaut très clairement mieux ne pas avoir de commentaires du tout que d'en avoir qui soient désynchronisés par rapport à ce que le code fait effectivement.

D'autant plus que, encore une fois, les noms explicites, le fait d'éviter le recours aux "sucres syntaxiques" et une indentations correcte permettront de comprendre le code beaucoup plus facilement

[GPPro]

Tout commentaire supplémentaire risque, tôt ou tard, de ne plus être représentatif de ce que fait effectivement le code, car celui qui corrige le code ne pensera que trop rarement à synchroniser les commentaires existants avec les modifications qu'il aura apportées.

J'ai vraiment du mal avec cet argument. "Parce que certains risquent de mal faire le boulot ou de ne pas le maintenir, il vaut mieux ne pas faire le boulot".

Je pense qu'il y a qu'en dev qu'on se permet de dire ce genre de chose. (Après je suis d'accord que dans 90% des cas le code se suffit à lui-même, mais il reste 10%).

[BenoitM]

J'ai vraiment du mal avec cet argument. "Parce que certains risquent de mal faire le boulot ou de ne pas le maintenir, il vaut mieux ne pas faire le boulot".

Je pense qu'il y a qu'en dev qu'on se permet de dire ce genre de chose. (Après je suis d'accord que dans 90% des cas le code se suffit à lui-même, mais il reste 10%).

De plus c'est considé qu'un développeur est assez bon pour faire du bon code mais pas assez bon pour maintenir des commentaire.

n code correctement écrit, avec des variables et des fonctions dont le nom est explicite, avec des fonctions n'ayant qu'une et une seule responsabilité, n'a a priori besoin d'aucun commentaire à partir du moment où l'on est en mesure de déterminer exactement le résultat que l'on est en droit d'attendre de la part de la fonction dans une situation donnée.

Mais as-tu déjà vu un code correctement écrit?
C'est bien de parler des mythes mais moi je parle de la vie réel.
et quand tu as dans une fonction 4-6 select dans une base de donnée qui se suivent je préfere lire ce qu'est sensé faire le select plutot que d'essayer de déchiffré un select.

[el_slapper]

Par expérience, les gens sont suffisamment fainéants que pour appliquer la loi du "moindre effort" lorsqu'ils essayent de comprendre un code.

C'est à dire que, s'ils ont le choix entre lire un texte qui décrit ce que le code est sensé faire et lire le code lui-même (ce que le code fait effectivement), ils vont forcément commencer par lire ce que le code est sensé faire et partir du principe que c'est ce que le code fait.

Ils risquent donc de perdre énormément de temps pour avoir passé un tronçon de code qu'ils estiment correct (sur base des commentaire) alors que l'erreur se trouve dans ce tronçon particulier, tout cela, pour finir tôt ou tard, n'ayant définitivement pas trouvé l'endroit où l'erreur se trouve, par revenir quand même sur le code lui-même et parfois trouver l'erreur en quelques secondes / minutes à peine.

Un code correctement écrit, avec des variables et des fonctions dont le nom est explicite, avec des fonctions n'ayant qu'une et une seule responsabilité, n'a a priori besoin d'aucun commentaire à partir du moment où l'on est en mesure de déterminer exactement le résultat que l'on est en droit d'attendre de la part de la fonction dans une situation donnée.

Pour être en mesure de déterminer ce résultat, le nom de la fonction (pour les plus simples) ou le cartouche (pour celles qui sont soumises à des pré ou post conditions) sont amplement suffisants.

Tout commentaire supplémentaire risque, tôt ou tard, de ne plus être représentatif de ce que fait effectivement le code, car celui qui corrige le code ne pensera que trop rarement à synchroniser les commentaires existants avec les modifications qu'il aura apportées.

C'est à ce moment là qu'il vaut très clairement mieux ne pas avoir de commentaires du tout que d'en avoir qui soient désynchronisés par rapport à ce que le code fait effectivement.

D'autant plus que, encore une fois, les noms explicites, le fait d'éviter le recours aux "sucres syntaxiques" et une indentations correcte permettront de comprendre le code beaucoup plus facilement

C'est pour ça que le commentaire doit être complémentaire du code. Pas le paraphraser - au mieux le résumer - mais aussi le compléter. Ainsi, le pourquoi est essentiel et un titre est aussi très important. (ce qui n'empêche pas tes règles de codage d'être indispensables).

[koala01]

J'ai vraiment du mal avec cet argument. "Parce que certains risquent de mal faire le boulot ou de ne pas le maintenir, il vaut mieux ne pas faire le boulot".

Je pense qu'il y a qu'en dev qu'on se permet de dire ce genre de chose. (Après je suis d'accord que dans 90% des cas le code se suffit à lui-même, mais il reste 10%).

Les dix pourcents restant, c'est les cas où il est vraiment important d'avoir un cartouche, mais pas du commentaire dans le code en lui meme

De plus c'est considé qu'un développeur est assez bon pour faire du bon code mais pas assez bon pour maintenir des commentaire.

C'est simplement prendre un fait certain en compte : écrire un commentaire au moment où l'on écrit pour la première fois du code est très facile, tout le monde est bien d'accord.

Mais modifier un commentaire existant pour lui faire prendre en compte les modifications apportées au code est beaucoup plus hasardeux et difficile... quand le développeur qui a apporté les modifications au code y pense ou en a tout simplement le temps.

Mais as-tu déjà vu un code correctement écrit?

Oui, et si ce n'est pas le cas, il est beaucoup plus facile de modifier la mise en page d'un code ou de renommer une variable ou une fonction que de commencer à revoir l'ensemble d'un commentaire qui commence peut etre à la première ligne de la fonction pour continuer aux dixièmes, treizièmes et dix-huitième lignes

C'est bien de parler des mythes mais moi je parle de la vie réel.
et quand tu as dans une fonction 4-6 select dans une base de donnée qui se suivent je préfere lire ce qu'est sensé faire le select plutot que d'essayer de déchiffré un select.

Je préfères que les différents sélect soient séparés dans différentes fonctions, quitte à ce qu'il y ait une fonction qui les concatène

Au moins, je sais quelle fonction fait quel type de select, et je n'ai pas à m'en inquiéter d'avantage

C'est pour ça que le commentaire doit être complémentaire du code. Pas le paraphraser - au mieux le résumer

C'est le role du cartouche qui doit exposer également les pré et post conditions, les éventuels invariants et expliquer le résultat que l'on attend de la part de la fonction [/QUOTE]- mais aussi le compléter. [/QUOTE]Un commentaire ne doit absolument pas compléter le code.

Si l'on parlait de compléter le code, cela impliquerait que le commentaire devrait faire quelque chose que le code ne fait absolument pas.

Comment voudrais tu qu'un commentaire puisse faire quelque chose en plus du code alors qu'il est, par nature, totalement ignoré par l'interpréteur / le compilateur

Si le code n'exprime pas clairement ce qu'il fait, c'est au développeur à veiller à le rendre plus explicite en choisissant mieux les noms utilisés, en améliorant la "mise en page", mais surement pas en rajoutant un commentaire qui risque de devenir obsolète à la première modification / correction.

Ainsi, le pourquoi est essentiel et un titre est aussi très important. (ce qui n'empêche pas tes règles de codage d'être indispensables).

Pourquoi aurais tu besoin de savoir le pourquoi

Tu n'as besoin du pourquoi que quand ton code est à visée pédagogique, histoire de donner une chance à celui qui le lit de s'habituer à faire la "transition" entre ce qu'il a, ce dont il a besoin et ce qu'il faut faire pour l'obtenir.

Une fois sorti de ce seul aspect pédagogique, tu n'a pas à t'inquiéter du pourquoi, vu qu'il correspond à tout ce qui a été mis en oeuvre pour arriver à une situation donnée.

Ce qui importe dans un code, c'est le comment car le pourquoi correspond à tout ce qui a mené l'exécution à la situation actuelle.

Or, comme tu viens si bien de le dire, un commentaire n'a pas à paraphraser le code. Il n'y a donc aucune raison d'indiquer le comment dans un code.

Mais du coup:

Si l'on considère que le pourquoi n'est pas utile en dehors d'un contexte purement pédagogique et que, de toutes manières, il ne serait que peu représentatif du "pourquoi" car il ne pourrait exprimer que la situation dans laquelle le développeur estime qu'il devrait se trouver.

Si l'on considère également que le commentaire n'a pas à indiquer le comment, qui est de la seule responsabilité du code.

Que reste-t-il à mettre dans les commentaires qui ne sont pas les cartouches

[Matthieu Vergne]

Là je suis pas d'accord: le pourquoi a son utilité, mais c'est justement dans des cas très précis qui rendent le code abscons, comme une optimisation. Le développeur peut deviner le comment en lisant le code (bien fait), mais pas le pourquoi. Si un code a des trucs bizarres dans une fonction qui semble basique, sans le pourquoi il peut être tenté de "corriger" ce code pour le clarifier, en suivant un pattern par exemple. Ajouter un commentaire donnant le pourquoi des trucs bizarre permet de comprendre l'utilité (et donc l'importance) de ces bouts de code, et ainsi éviter de les corrompre en pensant bien faire.

Mais ce genre de cas doit être rare, sinon c'est l'architecture qui n'est pas adaptée (car on passe notre temps à faire des trucs qui ne sont visiblement pas en accord avec, donc on n'a pas choisi la bonne).

En dehors d'un cas pédagogique donc, les commentaires (et non la doc) sont rarement utiles, mais restent utiles dans des cas bien précis : là où la complexité est nécessaire, et doit donc être compensée par des explications.

[Paul TOTH]

Les dix pourcents restant, c'est les cas où il est vraiment important d'avoir un cartouche, mais pas du commentaire dans le code en lui meme
C'est simplement prendre un fait certain en compte : écrire un commentaire au moment où l'on écrit pour la première fois du code est très facile, tout le monde est bien d'accord.

Mais modifier un commentaire existant pour lui faire prendre en compte les modifications apportées au code est beaucoup plus hasardeux et difficile...

en quoi est-il plus difficile de mettre à jour un commentaire dans le code que dans un cartouche ?!

[koala01]

en quoi est-il plus difficile de mettre à jour un commentaire dans le code que dans un cartouche ?!

Le fait est qu'un cartouche est beaucoup plus stable dans le temps, parce qu'il va contenir:

• une description de l'utilité de la fonction
• la liste des paramètres (s'il y en a)
• les éventuelles préconditions et postconditions
• la description de la valeur renvoyée (s'il y en a)
• les éventuelles exceptions lancées (s'il y en a)

A partir du moment où la responsabilité de la fonction a clairement été établie, ces informations resteront valables tant que la fonction fait partie de l'interface.

Si une quelconque de ces informations vient à devoir être modifiée, c'est, a priori, parce qu'on aurait en fait du écrire une autre fonction, sous peine de provoquer des régressions (OCP inside).

Mais, surtout, un cartouche n'a absolument pas pour but de faciliter la compréhension de l'implémentation de la fonction:

Son but est de savoir quand appeler la fonction, comment l'utiliser, les vérifications éventuelles à faire avant de transmettre les arguments et l'éventuelle gestion d'erreurs que l'utilisation de la fonction peut impliquer.

Un cartouche a une visée de documentation et peut d'ailleurs parfaitement servir à la génération automatique de documentation (que ce soit du javadoc, du doxygen ou meme des pages de "man" sous linux).

C'est au final parce que le but d'un cartouche est totalement différent et que le besoin de le mettre à jour est inexistant que je plaide pour la création d'un cartouche, mais que j'estime que les autres commentaires sont inutiles

NOTA: Mais j'ai déjà exposé mon point de vue dans les pages précédentes, tu n'as pas un peu l'impression de tourner en rond

[Matthieu Vergne]

Un cartouche n'a pas vocation à ne pas être retouché. Au même titre que n'importe quelle partie d'un programme, le cartouche aussi doit être mis à jour quand c'est nécessaire. Aucun programme n'est "bien fait" dès le départ, même pour des programmeurs très expérimentés, sinon c'est un programme qui t'a pris une journée pour un besoin très réduit que tu oublieras dans un coin.

Par contre, c'est vrai qu'un cartouche n'a pas pour but de dire ce qu'il y a dans la fonction. Typiquement, on a besoin d'effectuer une opération, on définit le prototype de la fonction qui devra s'en charger, on écrit la doc qui décrit les entrées sorties et autres informations utiles à son utilisation (comme cité plus haut), mais ce qu'il y a dedans est du ressort du développeur. Il peut changer le contenu de la fonction comme il veut tant que la fonction fait la même chose. Cependant, il sera bon de mettre à jour la doc en cas de changement du prototype (ajout/retrait/modification d'arguments) ou de la valeur de retour par exemple. Cela peut arriver après raffinage ou nettoyage, quand on se rend compte qu'il est préférable d'utiliser par exemple un type d'objet plus adapté ou quand plusieurs arguments se retrouvent déjà intégrés dans une structure de données (on fusionne donc les n arguments en un seul).

Le rôle de la fonction est probablement le plus stable, mais ça peut aussi changer un peu. Dire que ça ne doit pas changer "parce que ça correspond à une autre fonction", c'est une vision extrémiste. Les bonnes pratiques c'est une chose, mais il y en a certaines qui sont loin d'être toujours pratiques. On peut être amené à utiliser des pratiques strictes dans le cas où on fait des programmes critiques, mais ça coûte en temps, en effort voire en outils qui s'assurent que c'est respecté. Et ce coût il faut pouvoir le justifier. Si tu fais un programme qui peut bugger sans avoir de conséquences horribles (e.g. jeu vidéo) tu vas éviter de perdre temps et argent dans des pratiques trop rigoureuse. Tout les programmes ne visent pas à être utilisés dans des avions. Ou bien quoi, tu vas toujours faire des boucles avec un nombre d'itérations statique pour s'assurer que ça se finit avant un temps donné ?

Prendre le parti du "décide une fois et ne touche plus", même pour le cartouche, c'est rêver les yeux ouverts. Faut rester réaliste. Cependant, une fonction ne change pas comme de "trier une liste" à "afficher une interface", donc c'est évident qu'il y aura une certaine stabilité. En revanche, l'algo utilisé peut changer du tout au tout, par exemple passer d'un tri par insertion à un quicksort. Là on change quasiment tout. Et les commentaires doivent suivre.

Ici l'exemple est simple, il suffit de se dire "ben on efface tout et on recommence, les commentaires avec", mais en général les changements se font progressivement, et les commentaires restent. Par exemple, on passe d'un tri à bulle à un tri milkshake (tri à bulle dans les deux sens). Si les commentaires initiaux considèrent le sens unique mais restent globalement justes, le dév peut oublier de les changer, mais le suivant qui passe croit que c'est un tri à bulle à cause des commentaires et d'une structure globalement ressemblante, mais ne note pas la ligne avec le changement de sens. Et en touchant un truc en pensant bien faire, il fait une bêtise qui décale tout et le tri est corrompu.

[koala01]

Un cartouche n'a pas vocation à ne pas être retouché. Au même titre que n'importe quelle partie d'un programme, le cartouche aussi doit être mis à jour quand c'est nécessaire. Aucun programme n'est "bien fait" dès le départ, même pour des programmeurs très expérimentés, sinon c'est un programme qui t'a pris une journée pour un besoin très réduit que tu oublieras dans un coin.

Si ce n'est que ta fonction est créée et utilisée dans un but particulier.

Quelles que soient les modifications ou corrections apportées au code ou à l'algorithme, le but, les arguments et les conditions d'utilisations restent identiques.

Par contre, c'est vrai qu'un cartouche n'a pas pour but de dire ce qu'il y a dans la fonction. Typiquement, on a besoin d'effectuer une opération, on définit le prototype de la fonction qui devra s'en charger, on écrit la doc qui décrit les entrées sorties et autres informations utiles à son utilisation (comme cité plus haut), mais ce qu'il y a dedans est du ressort du développeur. Il peut changer le contenu de la fonction comme il veut tant que la fonction fait la même chose.

Exactement

Cependant, il sera bon de mettre à jour la doc en cas de changement du prototype (ajout/retrait/modification d'arguments) ou de la valeur de retour par exemple.

Là, on peut très sérieusement discuter...

Sur le type de retour, d'abord: Soit tu changes le type d'un objet polymorphe pour un type plus générique / spécifique compatible, et ton cartouche reste tout à fait valable.

Soit tu changes un "aucune valeur de retour" (void) en une valeur de retour, et tu dois rajouter l'information au cartouche, en effet.

Soit tu changes carrément le type de retour pour quelque chose d'incompatible, et l'on peut se dire que le but et l'utilisation de la fonction deviennent tout à fait différents: Tu ne pourras pas espérer changer le type de retour de ta fonction sans avoir à repasser chaque appel en revue afin de prendre le changement en compte ==> c'est bel et bien une nouvelle fonction qu'il te faut créer (avec le cartouche) si tu veux "simplement" pouvoir disposer de l'information renvoyée dans une situation particulière.

Le retrait "pur et simple" de paramètre, je n'y crois pas, pour la bonne et simple raison que, si tu as estimé qu'un valeur externe était nécessaire au début, elle restera nécessaire quoi qu'il arrive.

Bien sur, tu peux décider de supprimer le paramètre parce qu'il est devenu un membre de la classe, et, effectivement, cela occasionnera une modification du cartouche.

Mais, encore une fois, un tel changement ne sera jamais envisagé à la légère parce qu'il implique de modifier l'ensemble des appels à cette fonction

Je crois un peu d'avantage à l'ajout d'un paramètre à la fonction, sans doute en prenant soin d'y adjoindre une valeur par défaut (pour, justement, éviter d'avoir à repasser tous les appels en revue afin de rajouter le paramètre)

Effectivement, le cartouche devra être mis à jour

Cela peut arriver après raffinage ou nettoyage, quand on se rend compte qu'il est préférable d'utiliser par exemple un type d'objet plus adapté ou quand plusieurs arguments se retrouvent déjà intégrés dans une structure de données (on fusionne donc les n arguments en un seul).

C'est sans doute à cela que sert la surcharge des fonctions, non

Si tu veux éviter d'avoir à repasser l'ensemble des appels en revue, tu vas bien sagement laisser l'ancien prototype et l'ancienne implémentation là où ils sont et surcharger ta fonction... en y adjoignant le cartouche adéquat, quitte à ajouter une notion de déprécation au niveau du cartouche de la première version de cette fonction.

Il y a d'ailleurs de fortes chances que la surcharge se "contente" de faire appel à la première version de la fonction en "dispatchant" les arguments qu'elle reçoit

Le rôle de la fonction est probablement le plus stable, mais ça peut aussi changer un peu. Dire que ça ne doit pas changer "parce que ça correspond à une autre fonction", c'est une vision extrémiste.

Pas si tu limites les informations données à celles qui importent réellement à l'utilisateur.

Les bonnes pratiques c'est une chose, mais il y en a certaines qui sont loin d'être toujours pratiques. On peut être amené à utiliser des pratiques strictes dans le cas où on fait des programmes critiques, mais ça coûte en temps, en effort voire en outils qui s'assurent que c'est respecté. Et ce coût il faut pouvoir le justifier. Si tu fais un programme qui peut bugger sans avoir de conséquences horribles (e.g. jeu vidéo) tu vas éviter de perdre temps et argent dans des pratiques trop rigoureuse.

Est-ce à dire que tu préfères perdre du temps en débuggage

Tout les programmes ne visent pas à être utilisés dans des avions. Ou bien quoi, tu vas toujours faire des boucles avec un nombre d'itérations statique pour s'assurer que ça se finit avant un temps donné ?

je n'ai jamais rien dit de tel

Prendre le parti du "décide une fois et ne touche plus", même pour le cartouche, c'est rêver les yeux ouverts. Faut rester réaliste. Cependant, une fonction ne change pas comme de "trier une liste" à "afficher une interface", donc c'est évident qu'il y aura une certaine stabilité. En revanche, l'algo utilisé peut changer du tout au tout, par exemple passer d'un tri par insertion à un quicksort. Là on change quasiment tout. Et les commentaires doivent suivre.

Ici l'exemple est simple, il suffit de se dire "ben on efface tout et on recommence, les commentaires avec", mais en général les changements se font progressivement, et les commentaires restent. Par exemple, on passe d'un tri à bulle à un tri milkshake (tri à bulle dans les deux sens). Si les commentaires initiaux considèrent le sens unique mais restent globalement justes, le dév peut oublier de les changer, mais le suivant qui passe croit que c'est un tri à bulle à cause des commentaires et d'une structure globalement ressemblante, mais ne note pas la ligne avec le changement de sens. Et en touchant un truc en pensant bien faire, il fait une bêtise qui décale tout et le tri est corrompu.

De deux choses l'une:

Soit tu as une seule fonction qui effectue le tri, et l'utilisateur n'a strictement pas à savoir quel sorte de tri est utilisé (le but de la fonction est de trier les données).

Soit tu donnes le choix de choisir "en connaissance de cause" tel algorithme de tri plutôt que tel autre, mais, dés qu'on parle de choix, c'est qu'il existe bel et bien deux au moins deux fonctions distinctes, avec des noms distincts, et pour lesquelles on s'attend à ce que le cartouche indique explicitement l'algorithme utilisé.

Seulement, dans ce cas, il tout changement d'algorithme passera par la création d'une nouvelle fonction... et du cartouche correspondant.

Tout cela pour dire qu'il est, effectivement, possible que l'on doive, à un moment ou à un autre en venir à envisager la modification de certains cartouches, mais le besoin de modifications à apporter au cartouche seront beaucoup moins fréquents que les besoin d'apporter des modifications au code et, surtout, la plupart des besoins de modifications seront dus à des décisions de conception, non à des corrections / améliorations de code strico sensu.

[Matthieu Vergne]

Tout cela pour dire qu'il est, effectivement, possible que l'on doive, à un moment ou à un autre en venir à envisager la modification de certains cartouches, mais le besoin de modifications à apporter au cartouche seront beaucoup moins fréquents que les besoin d'apporter des modifications au code et, surtout, la plupart des besoins de modifications seront dus à des décisions de conception, non à des corrections / améliorations de code strico sensu.

Toi aussi, tu aimes avoir le dernier mot, hein ? {^o^}

[el_slapper]

(.../...)Si l'on considère que le pourquoi n'est pas utile en dehors d'un contexte purement pédagogique et que, de toutes manières, il ne serait que peu représentatif du "pourquoi" car il ne pourrait exprimer que la situation dans laquelle le développeur estime qu'il devrait se trouver.

De mon expérience, TOUT code a un interêt pédagogique. Pour le nouveau venu qui essaye de s'y retrouver. Pour le chef qui cherche un exemple, ou une compréhension. Pour l'outilleur(moi) qui fait une analyse transversale pour préparer un nouvel outil de tests automatiques. Pour la MOA qui peut demander à comprendre un truc précis. Pour le stagiaire qui veut un bel exemple à coller dans son rapport de stage. etc.....

De plus, les docs ont une furieuse tendance à disparaitre. Quand les équipes changent, déménagent, sont fusionnées-acquises, on se retrouve souvent avec du code brut. Et un cartouche qui précise "se référer à la demande 1187" alors que celle-ci n'est plus disponible n'est pas très utile.

Après, je suis conscient que mon parcours est un peu particulier, et que tout le monde n'a pas l'occasion de travailler sur du code de 20, 30 voire 40 ans d'âge. Mais je crois que ça va augmenter. Java semble être là pour durer, et le code java va être de plus en plus vieux. De plus en plus, il va survivre à son entité créatrice, à sa documentation créatrice, et devra pouvoir être compris tel quel. C'est pour ça que le "Pourquoi" est toujours essentiel.

36 ans plus tard, je suis tombé sur un code qui changeait le code routage pour l'Alsace Moselle, et limitait à 8 chiffres décimales comprises le montant du paiement par TIP. Il a fallu pas mal de recherches pour comprendre que la deuxième règle était liée au préimprimé des TIP. Et on a jamais trouvé le pourquoi de la première règle.

Code :

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

1
2
3
4
IF TYPE-PAIMENT-TIP AND MONTANT-PAIEMENT >= 100000000
    SET TYPE-PAIMENT-CHEQUE TO TRUE
END-IF
.

C'est parfaitement lisible et compréhensible, même pour qui n'a jamais vu de COBOL, sauf que quand on fait une refonte et qu'on n'a pas le petit commentaire qui va bien, on ne sait pas ce qu'il faut en faire :

Code :

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

*Les préimprimés TIP sont limités à 6 chiffres avant la virgule.

Et je ne sais toujours pas pourquoi nous avions :

Code :

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

1
2
3
4
5
IF CODE-REGION-ALSACE
    MOVE 151 TO CODE-ROUTAGE
ELSE
    MOVE 101 TO CODE-ROUTAGE
END-IF

(valeurs changées à fin de confidentialité)
Un peu de pédagogie nous aurait évité de reproduire ceci à l'aveugle dans le nouveau système.

[Matthieu Vergne]

Je vais pas dire que tu as tort, mais il ne faut pas trop généraliser. En gros tu peux faire valoir cette remarque pour tout et n'importe quoi : si tu as une information complémentaire dans plusieurs documents séparés, le fait d'en perdre certains fait que tu n'as plus qu'une partie de l'info. Néanmoins, ça ne justifie pas de tout mettre au même endroit, sinon on ne s'y retrouve plus. Avec ta remarque, sans aller plus loin, la solution est d'avoir "dans le code" toutes les discussions qui ont menées au cahier des charges, le cahier des charges, le code, le code du benchmark qui aurait permi de valider tout ça, les potentiels feedbacks des utilisateurs, etc. et bien entendu l'historique de tout ça. Parce qu'après tout, on ne sait jamais, ça pourrait servir à quelqu'un de comprendre pourquoi on en est arrivé là.

On implémente toujours quelque chose pour une raison (aussi saugrenue ou personnelle soit-elle), mais ça ne veut pas dire qu'il faut mettre le pourquoi de chaque ligne. Si c'est quelque chose qui vient du cahier des charges, alors c'est considéré comme une généralité dans le projet, et donc une connaissance de base à avoir pour comprendre le programme. Si c'est propre au développement, là oui il est important de préciser le pourquoi, car ce n'est pas quelque chose que tu vas retrouver dans le cahier des charges, donc ce n'est pas quelque chose que le lecteur devrait avoir en tête.

[Matthieu Vergne]

Tiens oui, j'oubliais une utilisation assez fréquente que j'ai des commentaires. peut-être que ça donnera un nouvel élan à la discussion.

Dans beaucoup de cas on fait un traitement spécial si une condition est remplie, sinon on ne la fait pas :

Code :

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

1
2
3
4
5
if (condition) {
	traitement spécial
}
traitement global

Le soucis, c'est que ça laisse implicite le traitement dans le cas où la condition n'est pas remplie (qui est "on ne fait rien"). Pour m'assurer d'avoir bien intégrer tous les cas possibles, je ne fais jamais de if sans else :

Code :

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

1
2
3
4
5
6
7
if (condition) {
	traitement spécial
} else {
	...
}
traitement global

En l'occurrence, si on n'est pas censé faire quoi que ce soit dans ce else, ça se traduit par un commentaire qui décrit dans quels cas on est censé paser par là :

Code :

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

1
2
3
4
5
6
7
if (condition) {
	traitement spécial
} else {
	// quels cas passent normalement par là
}
traitement global

Le contenu du commentaire sert à montrer les cas auxquels on a pensé. Ça doit bien entendu être le complémentaire des ifs qui le précèdent. Si ce n'est pas le cas, il y a une erreur quelque part (commentaire ou conditions). Ce n'est pas le genre d'erreur que l'IDE peut voir, c'est donc une aide en plus pour le débogage. Et ce n'est pas simplement une question de mise à jour de commentaire quand on change le code qu'il faut avoir à l'esprit. L'idée est que c'est une "ligne de code" qui ne fait rien, et qui dit explicitement pourquoi elle ne fait rien. Le ligne de commentaire se commente elle-même en gros, elle ne commente pas une autre ligne. Ce n'est donc pas parce qu'on change une ligne avant ou après qu'on doit changer celle-là.

C'est un peu philosophique, mais en allant plus loin ça force aussi à prendre en compte les cas qui ne doivent pas arriver, et là je génère une exception :

Code :

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

1
2
3
4
5
6
7
if (condition) {
	traitement spécial
} else {
	throw new Exception("Ce cas ne devrait pas arriver.")
}
traitement global

Pareil pour les switchs avec la clause default.

[Paul TOTH]

Je vais pas dire que tu as tort, mais il ne faut pas trop généraliser. En gros tu peux faire valoir cette remarque pour tout et n'importe quoi : si tu as une information complémentaire dans plusieurs documents séparés, le fait d'en perdre certains fait que tu n'as plus qu'une partie de l'info. Néanmoins, ça ne justifie pas de tout mettre au même endroit, sinon on ne s'y retrouve plus.

J'ai du reprendre un projet vieux de 15 ans d'après la version compilée et le listing des sources sur microfiche...et rien d'autre ! Les rares commentaires étaient les bienvenus.

Pour moi la doc hors source n'est pas à destination des programmeurs en premier lieu. Elle est là pour les chefs de projets voir les décideurs qui l'ont écrite ou la consulte pour comprendre les tenants et aboutissant du projet.

Les commentaires dans le code source n'ont pas vocation à être lus par autre chose qu'un programmeur. Ils sont la pour éviter de jongler avec le CdC et expliquer les choix d'implémentation. Tout mettre au même endroit c'est à mon sens la meilleures solution pour avoir quelque chose le plus à jour possible. On nous dit régulièrement que les commentaires sont désynchronisés du code, mais c'est à mon sens bien pire quand le commentaire est à un autre endroit.

Avec ta remarque, sans aller plus loin, la solution est d'avoir "dans le code" toutes les discussions qui ont menées au cahier des charges, le cahier des charges, le code, le code du benchmark qui aurait permi de valider tout ça, les potentiels feedbacks des utilisateurs, etc. et bien entendu l'historique de tout ça. Parce qu'après tout, on ne sait jamais, ça pourrait servir à quelqu'un de comprendre pourquoi on en est arrivé là.

ça serait pas mal, mais peu réaliste car cela n'implique pas que des programmeurs, qui sont les seuls supposés mettre le nez dans le code. et ils ont autrechose à faire que de rédiger des comptes rendus de réunion dans leur code.

On implémente toujours quelque chose pour une raison (aussi saugrenue ou personnelle soit-elle), mais ça ne veut pas dire qu'il faut mettre le pourquoi de chaque ligne.

non mais chaque concept ça serait pas mal, et un concept expliqué en quelques mots peut se traduire en plusieurs centaines de lignes de code.

C'est un peu philosophique, mais en allant plus loin ça force aussi à prendre en compte les cas qui ne doivent pas arriver, et là je génère une exception :

Code :

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

1
2
3
4
5
6
7
if (condition) {
	traitement spécial
} else {
	throw new Exception("Ce cas ne devrait pas arriver.")
}
traitement global

ce dernier cas est une assertion

Code :

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

1
2
3
  Assert(!condition, "Ce cas ne devrait pas arriver');
  traitement global;

[Matthieu Vergne]

ce dernier cas est une assertion

Code :

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

1
2
3
  Assert(!condition, "Ce cas ne devrait pas arriver');
  traitement global;

C'est pas tout à fait la même chose. Tu utilises une assertion pour vérifier une condition, et si elle n'est pas respectée tu génère une exception. Mais si elle est vérifiée tu ne fais rien du tout. Son équivalent serait :

Code :

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

1
2
3
4
5
6
if (condition) {
    // tout va bien
} else {
    throw new Exception("Ce cas ne devrait pas arriver")
}

Moi non, le premier bloc dispose d'un traitement, ce n'est donc pas la même chose. Et comme c'est de là que je pars (if avec traitement mais sans else), c'est clairement incompatible avec l'idée d'assertion. De plus, pourquoi vérifier la condition une fois pour faire mon traitement si c'est pour revérifier la condition une autre fois ensuite avec une assertion qui génèrera l'exception si ce coup-ci c'est faux ? Autant utiliser le else plutôt que faire deux foix la vérification, surtout si après le if la condition peut avoir changé. Conceptuellement, ce serait faux.

[Paul TOTH]

C'est pas tout à fait la même chose. Tu utilises une assertion pour vérifier une condition, et si elle n'est pas respectée tu génère une exception. Mais si elle est vérifiée tu ne fais rien du tout. Son équivalent serait :

Code :

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

1
2
3
4
5
6
if (condition) {
    // tout va bien
} else {
    throw new Exception("Ce cas ne devrait pas arriver")
}

Moi non, le premier bloc dispose d'un traitement, ce n'est donc pas la même chose. Et comme c'est de là que je pars (if avec traitement mais sans else), c'est clairement incompatible avec l'idée d'assertion. De plus, pourquoi vérifier la condition une fois pour faire mon traitement si c'est pour revérifier la condition une autre fois ensuite avec une assertion qui génèrera l'exception si ce coup-ci c'est faux ? Autant utiliser le else plutôt que faire deux foix la vérification, surtout si après le if la condition peut avoir changé. Conceptuellement, ce serait faux.

non c'est la même chose
j'ai mis !condition en assertion.

de plus ça me parait douteux d'écrire une condition sur un code qui doit toujours s'exécuter...puisque tous les autres cas sont des cas d'erreur.

L'assertion est la bonne solution, sauf si éventuellement tu veux systématiquement inclure l'exception, même en mode release.

mais bon tout cela n'a pas grand chose à voir avec les commentaires

[koala01]

Attention!!!

Il faut savoir qu'une assertion et une exception ont, fondamentalement, des rôles différents et des utilisations différentes!

Il ne faut déjà pas oublier qu'un assert ne sera actif qu'en mode debug, ce qui fait que, si, pour une raison ou une autre, le cas où l'assertion échoue n'est pas traitée "par ailleurs", le code continuera à fonctionner (enfin, si l'on peut dire!) en mode release.

Ainsi, un code proche de

Code C++ :

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

1
2
3
4
void foo(Type * ptr){
    assert(ptr!=NULL);
    ptr->someField = someValue;
}

lancera une assertion en mode débug et... plantera lamentablement en release (sur une erreur de segmentation) si l'on transmet NULL comme paramètre

Une exception permet de faire remonter une erreur jusqu'à ce qu'on soit en mesure de la traiter, mais, a priori, une exception devrait rester réservée aux seuls cas... exceptionnels (donc, n'étant théoriquement pas sensés se produire, mais se produisant malgré tout de temps en temps).

J'ai personnellement eu à travailler sur un projet qui était bourré d'assert dans ce genre, et qui plantait régulièrement "simplement" parce que le pointeur transmis valait null à cause de scénario non gérés dans les tests unitaires, et je peux t'assurer que ca devient vite lassant

Enfin, il est vrai que l'assert est régulièrement utilisé pour représenter une précondition (et parfois, à tord, pour représenter une postcondition), mais, s'il faut être en mesure d'indiquer à l'utilisateur que la précondition n'est pas remplie afin qu'il puisse "faire le nécessaire" pour résoudre le problème, un assert seul ne suffit généralement pas