Faut-il commenter son code source pour le rendre plus lisible et maintenable ?

[gl]

Envoyé par hegros

FIRST_ELEMENT_STARTS_WITH_1_NO_0_CONVENTION_LIB_XXX

/* Attention, la bibliothèque XXX indice ces éléments de 1 à n.
Le premier élément se trouve donc à l'indice 1 et non 0. */

Ca choque à ce point ?

Oui bien sur

Plus sérieusement, non ce n'est pas choquant juste lourd (enfin de mon point de vue), tu te traines un nom à rallonge qui n'est au final qu'une reprise du commentaire à la différence qu'il est difficile à mettre en forme et dans un langage non naturel (ce n'est pas de l'anglais ou du français correct).

Mais ma question est surtout, particulièrement si cette constante n'est utilisée qu'à cet endroit, qu'elle est la plus value de ce nom par rapport au commentaire initiale ?

Envoyé par white_tentacle

Ce que je retiens de cet exemple, c'est qu'une lib devrait fournir des itérateurs (ou similaire), plutôt que d'utiliser une convention implicite ou explicite...

J'ai eu le problème en migrant une appli vb6 vers vb.net, c'est tellement la merde avec les indices, qu'au final, j'ai tout passé en boucle for each pour être sûr de ne pas me planter.

Pour les langages qui fournissent des itérateurs, des boucle for each ou d'autres mécanismes plus ou moins équivalent, c'est certes préférable (et pas uniquement d'un point de vue de l'expressivité d'ailleurs), malheureusement tous les langages ne le proposent, et même pour les langages qui le proposent encore faut-il que la bibliothèque le supporte. C'est un peu tout le problème de devoir utiliser des bibliothèques (framework, SDK ou autre d'ailleurs) externes pour lequel il n'y a pas d'alternative viable, tu es extrêmement dépendant de leur choix même lorsque ces choix sont visiblement mauvais.

[hegros]

Envoyé par gl

Plus sérieusement, non ce n'est pas choquant juste lourd (enfin de mon point de vue), tu te traines un nom à rallonge qui n'est au final qu'une reprise du commentaire à la différence qu'il est difficile à mettre en forme et dans un langage non naturel (ce n'est pas de l'anglais ou du français correct).

ok de mon point de vue le commentaire est juste lourd pas choquant non enfin plus lourd qu'une constante

Envoyé par gl

Mais ma question est surtout, particulièrement si cette constante n'est utilisée qu'à cet endroit, qu'elle est la plus value de ce nom par rapport au commentaire initiale ?

il faudrait déja trouver une plus value à ce commentaire n'adhérant pas du tout à ce type de commentaire qui est une spécification technique au final


l'avantage c'est qu'on comprends aussi bien avec une constante qu'avec le commentaire, mais avec moins de caractère, alors si en une ligne (compilable) il est possible d'exprimer sans ambiguité une obscurité de code alors pourquoi se prendre la tête d'en écrire 3 ?

autre avantage cela compacte le code source et notamment la fonction où se trouve cette portion de code puisque la constante serait plutot défini en tête de fichier soit directement on a l'information pas la peine de descendre au fin fond du source pour se le rappeler. Voilà pour la lisibilité.

De plus nous sommes parti sur un exemple exceptionnel soit on trouverait plus d'intérêt avec un exemple courant mais pour moi cela me semble bien suffisant..

[gl]

Envoyé par hegros

l'avantage c'est qu'on comprends aussi bien avec une constante qu'avec le commentaire, mais avec moins de caractère, alors si en une ligne (compilable) il est possible d'exprimer sans ambiguité une obscurité de code alors pourquoi se prendre la tête d'en écrire 3 ?

Car il est difficile avec un faible nom de mots d'exprimer certaines subtilités et précisions qu'il est simple de faire passer avec 2 ou 3 phrases bien tournées.

Envoyé par hegros

autre avantage cela compacte le code source et notamment la fonction où se trouve cette portion de code puisque la constante serait plutot défini en tête de fichier soit directement on a l'information pas la peine de descendre au fin fond du source pour se le rappeler. Voilà pour la lisibilité.

Oui et non.

C'est effectivement un argument pertinent. Cependant avec des fonctions courtes, la différence (et donc l'avantage) est assez ténue.

[hegros]

Envoyé par gl

Car il est difficile avec un faible nom de mots d'exprimer certaines subtilités et précisions qu'il est simple de faire passer avec 2 ou 3 phrases bien tournées.

Ok...Les exemples aussi sont difficiles à trouver ne serait-ce qu'un exemple académique bien que je doute qu'il puisse en exister vraiment... Il n'y a même pas un article ou un tutorial la dessus mince !

Envoyé par gl

C'est effectivement un argument pertinent. Cependant avec des fonctions courtes, la différence (et donc l'avantage) est assez ténue.

Si les fonctions sont courtes un bloc de commentaire aussi gros que la fonction en plein milieu au dessus ou en dessous cela fait tâche.

Arrêtons ici parce que si les commentaires étaient si utiles à la lisibilité ou à la maintenabilité il y aurait beaucoup plus d'exemples qui fuserait sur le post pour le démontrer et ce n'est pas le cas. Open-source ou pas.

[gl]

Envoyé par hegros

Arrêtons ici parce que si les commentaires étaient si utiles à la lisibilité ou à la maintenabilité il y aurait beaucoup plus d'exemples qui fuserait sur le post pour le démontrer et ce n'est pas le cas. Open-source ou pas.

Juste une petite précision pour déterminer. Comme je l'ai déjà dit [1], les cas où ils sont utiles ne sont pas fréquent du tout mais pas inexistant non plus.
Utile n'implique pas fréquent et rare n'implique pas inutile.


[1] Je n'avais peut être pas assez insisté sur ce point, mais ça reste des cas exceptionnels et donc forcément il ne sont pas légion (en dehors des commentaires d'en-tête de fonctions publiques, mais c'est un autre point).

[brettm]

D'une manière générale, je conseille de commenter le 'pourquoi' plutôt que le 'comment'.

Pour le 'comment' il vaut mieux essayer de rendre son code lisible. En utilisant des noms représentatifs bien sûr mais aussi en encapsulant une portion de code dans des méthodes, en extrayant des classes qui font sens...

Un bon truc à garder en tête: si vous vous sentez obligés de commenter une portion de code, essayer d'extraire ce code dans une méthode dont le nom sera aussi descriptif que l'aurait été le commentaire.

Je vous rassure, il y a toujours des cas où on a besoin de décrire ce que fait le code.

Pour les API, c'est une autre histoire. Là il vaut mieux être assez descriptif avec des exemples.

[hegros]

Envoyé par gl

Juste une petite précision pour déterminer. Comme je l'ai déjà dit [1], les cas où ils sont utiles ne sont pas fréquent du tout mais pas inexistant non plus.
Utile n'implique pas fréquent et rare n'implique pas inutile.

A priori ils sont utiles et fréquents pour 95% des sondés ce qui est étonnant pour la maintenabilité c'est comme si tout les votants étaient unixiens ou open-sourcer

[souviron34]

Envoyé par brettm

D'une manière générale, je conseille de commenter le 'pourquoi' plutôt que le 'comment'.

Absolument, c'est ce qu'on dit depuis le début..

Envoyé par brettm

Un bon truc à garder en tête: si vous vous sentez obligés de commenter une portion de code, essayer d'extraire ce code dans une méthode dont le nom sera aussi descriptif que l'aurait été le commentaire.

tu n'as pas bien lu ce qu'on a dit plus haut..

Envoyé par hegros

A priori ils sont utiles et fréquents pour 95% des sondés ce qui est étonnant pour la maintenabilité c'est comme si tout les votants étaient unixiens ou open-sourcer

C'est au contraire pour s'être (longuement) frottés aux problèmes de maintenabilité que 95% des gens pensent comme ça...

Envoyé par hegros

Admirez le sondage, 160 contrôlés positifs au test du commentaire, c'est plutôt (pas le chien de mickey) une pandémie numérique lié au dogme 'académique' et des cascadeurs (en hommage au cycle en cascade)

Le commentaire dans mon environnement c'est ce qu'on appelle une rumeur.

Eh bien encore une fois, puisque tu parles de centrales, et qu'une central ane durée de vie de 40 ans, je souhaite beaucoup de café à des repreneurs dans 25 ans !!!!!


Maintenant, les 100 derniers messages ne sont qu'un commentaire totalement inutile et stupide par rapport au sujet de ce thread..

Je vous quitte, car, comme Garulfo, vous faites plus que m'embêter, vous m'emm.rdez..

Et surtout vous faites valoir de mauvaises habitudes ..

Je m'en fous un peu, je serais depuis longtemps à la retraite.. Mais je trouve dommage de gaspiller de la bande passante sur ce forum extrêmement parcouru par des débutants pour y prôner des habitudes de hackers..

[Félix Guillemot]

En voilà un débat passionnant, je suis tombé dessus grâce à la newsletter...
Je vais répondre comme il se doit !

J'ai commencé la programmation à 11 ans et j'en ai 36, avec 11 ans de missions dans des grandes boîtes. Mon expérience m'a conduit à écrire un livre, sûrement ressentant le besoin de faire un bilan de toutes ces années de code mais aussi de partager ce que je sais et qui pourrait, sans prétention, être utile à la communauté de mes confrères développeurs. Ce livre s'appelle "Le développement informatique durable". Vous trouverez une critique de Laurent Dardenne sur le site : http://conception.developpez.com/liv...L9782746222465

Ce livre défend de façon militante le développeur, souvent considéré injustement comme « l'ouvrier en bleu de travail de l'informatique », et il délivre ensuite certaines clés liées à la méthode qui doivent lui permettre d'accroitre de façon très significative ses performances.

Parmi ces clés, l'utilisation des commentaires à une place primordiale.
En effet, l'utilisation des commentaires n'a pas pour seul objectif de documenter le code pour nos successeurs ou encore nous même comme on nous le rabâche sans cesse : il doit permettre de donner une forme consciente à la pensée à l'état de fermentation consignées dans notre esprit.
Je m'explique avant qu'on croie que je viens de fumer le St Maclou de Velizy2 :
Pour réaliser ce que l'on pense et évaluer la pertinence de notre raisonnement, il est très utile, voire essentiel, de formaliser cette pensée, et la façon la plus efficace de le faire, hormis la parole est l'écriture.
Ainsi, les commentaires qui précéderont l'écriture de tout code vont "imprimer" notre pensée, et à la lecture de celle-ci, nous allons nous rendre compte des éventuelles lacunes de notre raisonnement pour le repenser, le reformuler et ainsi de suite jusqu'à arriver à une forme juste.

Lorsque ce raisonnement sera arrivé à maturité par l'aller-retour entre les pensées et l'écriture, nous procéderons à la seconde phase qui est l'écriture du code. Vous verrez alors avec quelle fluidité il se déroule puisqu'il n'est plus alors qu'une simple traduction syntaxique. Pour appliquer moi même cette méthode et l'avoir installée dans mon comportement de développeur, j'ai vu mes performances s'accroître d'une façon très significative : code écrit beaucoup plus vite, beaucoup moins de bugs, sérénité…

J'ai nommé cette méthode "l'écriture analytique".
Le chapitre qui lui succède se nomme "l'utilité des commentaires enfin révélée".

On ne peut pas dire que je viens juste faire de la pub pour un bouquin, je pense que ce débat était l'endroit idéal pour en parler.

Pour résumer mon avis, les commentaires sont INDISPENSABLES, d'abord parce qu'ils document le code mais surtout, et c'est là à mon sens la véritable utilité des commentaires, parce qu'ils permettent de structurer et murir notre raisonnement en le façonnant telle une sculpture pour donner ensuite une fluidité incroyable au code et des performances exceptionnelles, où du moins d'un niveau professionnel.

Une vidéo gratuite qui traite du sujet avec démo à l'appui est disponible sur developpez.com : http://delphi.developpez.tv/delphi2008/#session2

[Vlade]

Les développeurs vont sans doute critiquer mais en tant que manager je trouve ce poste de Félix très bien.
Pour allez plus loin je dirai même que tous les commentaires doivent être disponible en temps réel à toute l'équipe et accompagné le code.
Je m'explique: Si on a une documentation high level avec juste quelques diagramme c'est pas terrible car on voit pas les commentaires du développeurs dedant, on voit juste ceux de l'architecte. Si on a une documentation papier détaillée il faut allez la chercher à chaque fois (perte de temps important) en plus elle ne peut être remise à jour automatiquement.
L'idéal est la solution du milieu associant diagramme plus commentaire en même temps disponible pour toute l'équipe et en accès immédiat (je veux dire click bouton).

[chaplin]

Je suis quand même surpris que 14 personnes disent qu'il n'y a pas besoin de commentaire. Si on se tient au sondage stricto sensu, c'est 7%.

[Gilliard]

Bien évidemment oui. Mais
- Comme déjà dit, le "pourquoi" doit primer sur le "comment"
- Et ne jamais oublier que la meilleure des documentations, c'est la qualité et la systématique du nomage des classes / méthodes / variables etc. (et des fichiers qui les contiennent !) .
Par exemple, pas une fois
"int GetMonTruc()" , "void SetMonTruc(int i)"
et une autre
"int MonMachinGet()" , "void MonMachinSet(int i)"
ou pire
"int GetTaChose()" , et son (non-symétrique) "void TaChoseSet(int i)

[renoo]

Envoyé par bugsan

Moi je m'arrange pour avoir des méthodes qui contiennent moins de 20 lignes de code, idéalement moins de 10 (pour ceux que ça ferait rire : allez jeter un œil à Spring). Et je mets tout le commentaire dans la javadoc. C'est très rare que je commente directement au milieu du code. Je trouve que ça réduit la visibilité.

Je suis assez d'accord avec le fait que les commentaires au milieu d'une fonction ne sont souvent pas nécessaires... et dans le cas où ils le sont c'est surement que la fonction fait plus de 10 lignes. Le problème dans ce cas, c'est plutot de casser et refactoriser les fonctions trop grosses ; plutôt que de mettre des commentaires. Un autre souci avec les commentaires, c'est que que l'on risque de décrire 2 fois la même chose (la seule explication c'est alors que le code n'est pas vraiment lisible)... Dans ces deux descriptions, le code réel peut être testé (via des tests unitaires pex) par contre les commentaires ne le sont pas.

Je vote donc pour "pas de commentaires" comme un objectif (ne pas en avoir besoin pour que le code soit lisible).

[Félix Guillemot]

L'utilité des commentaires n'est pas uniquement de documenter le code :

En voilà un débat passionnant, je suis tombé dessus grâce à la newsletter...
Je vais répondre comme il se doit !

J'ai commencé la programmation à 11 ans et j'en ai 36, avec 11 ans de missions dans des grandes boîtes. Mon expérience m'a conduit à écrire un livre, sûrement ressentant le besoin de faire un bilan de toutes ces années de code mais aussi de partager ce que je sais et qui pourrait, sans prétention, être utile à la communauté de mes confrères développeurs. Ce livre s'appelle "Le développement informatique durable". Vous trouverez une critique de Laurent Dardenne sur le site : http://conception.developpez.com/liv...L9782746222465

Ce livre défend de façon militante le développeur, souvent considéré injustement comme « l'ouvrier en bleu de travail de l'informatique », et il délivre ensuite certaines clés liées à la méthode qui doivent lui permettre d'accroitre de façon très significative ses performances.

Parmi ces clés, l'utilisation des commentaires à une place primordiale.
En effet, l'utilisation des commentaires n'a pas pour seul objectif de documenter le code pour nos successeurs ou encore nous même comme on nous le rabâche sans cesse : il doit permettre de donner une forme consciente à la pensée à l'état de fermentation consignées dans notre esprit.
Je m'explique avant qu'on croie que je viens de fumer le St Maclou de Velizy2 :
Pour réaliser ce que l'on pense et évaluer la pertinence de notre raisonnement, il est très utile, voire essentiel, de formaliser cette pensée, et la façon la plus efficace de le faire, hormis la parole est l'écriture.
Ainsi, les commentaires qui précéderont l'écriture de tout code vont "imprimer" notre pensée, et à la lecture de celle-ci, nous allons nous rendre compte des éventuelles lacunes de notre raisonnement pour le repenser, le reformuler et ainsi de suite jusqu'à arriver à une forme juste.

Lorsque ce raisonnement sera arrivé à maturité par l'aller-retour entre les pensées et l'écriture, nous procéderons à la seconde phase qui est l'écriture du code. Vous verrez alors avec quelle fluidité il se déroule puisqu'il n'est plus alors qu'une simple traduction syntaxique. Pour appliquer moi même cette méthode et l'avoir installée dans mon comportement de développeur, j'ai vu mes performances s'accroître d'une façon très significative : code écrit beaucoup plus vite, beaucoup moins de bugs, sérénité…

J'ai nommé cette méthode "l'écriture analytique".
Le chapitre qui lui succède se nomme "l'utilité des commentaires enfin révélée".

On ne peut pas dire que je viens juste faire de la pub pour un bouquin, je pense que ce débat était l'endroit idéal pour en parler.

Pour résumer mon avis, les commentaires sont INDISPENSABLES, d'abord parce qu'ils document le code mais surtout, et c'est là à mon sens la véritable utilité des commentaires, parce qu'ils permettent de structurer et murir notre raisonnement en le façonnant telle une sculpture pour donner ensuite une fluidité incroyable au code et des performances exceptionnelles, où du moins d'un niveau professionnel.

Une vidéo gratuite qui traite du sujet avec démo à l'appui est disponible sur developpez.com : http://delphi.developpez.tv/delphi2008/#session2

[jahbromo]

Commenter oui ! mais il faut eviter de commenter les commentaires aussi