Discussion :

[hegros]

non j'en comprends pas vraiment l'interet dans d'autres buts oui sinon en général effectivement je ne les trouve pas utile à vrai dire 80% des cas.

et effectivement je ne les lis pas tous car c'est ridicule et sans interet surtout si la moitié concerne l'exegese de partie plus ou moins douteuse du programme....

il suffit de voir les exemples de code avec commentaire donnés dans l'autre post y'en a aucun qui est à mon gout pertinent et qui pourrait m'être utile si je devais reprendre le code. Peut-être faut-il inclure une matière en GL 'apprendre à écrire un commentaire'.

[hegros]

Si le sondage a un interet c'est que quelque part les commentaires posent problèmes, c'est limite dogmatique on en vient à en écrire parce qu'en gl il est dit qu'il faut en écrire.

Il y en a même qui en font des sites

[gl]

il suffit de voir les exemples de code avec commentaire donnés dans l'autre post y'en a aucun qui est à mon gout pertinent et qui pourrait m'être utile si je devais reprendre le code. Peut-être faut-il inclure une matière en GL 'apprendre à écrire un commentaire'.

Je pense que tu oublies un élément important, tu n'es pas tout seul. D'autres personnes vont un jour ou l'autre travailler sur ses sources, d'autres vont utiliser les APIs mises à leur disposition, d'autres vont devoir faire des formations sur cette bibliothèque, etc.

Qu'un commentaire ne te soit d'aucune utilité à toi qui a écris le code c'est une chose et je dirais presque que c'est normal. Qu'il ne soit d'aucune utilité à personne c'est autre chose (et dans ce cas, c'est clair qu'il n'a aucune raison d'être).
Pour reprendre ce que tu disais plus haut, il est fort probable que personne ne lise tous les commentaires d'un code. Par contre il est beaucoup moins probable que tous les commentaires ne soient pas lu au moins une fois par quelqu'un.


Par curiosité, peux-tu préciser ton contexte de travail. Car à lire tes remarques, j'ai l'impression que tu travailles tout seul sur des projets d'une durée assez brève sans trop d'évolution et que tu ne livres que des exécutables complets, jamais des bibliothèques, modules, classes ou autres qui seront utilisées par d'autres développeurs.

[hegros]

gl j'ai suffisamment utiliser de code source d'autres interne ou externe pour connaître le problème. Tu n'as pas l'air sensible au problème d'interpretation lorsqu'il s'agit de commentaire purement du domaine fonctionnel parce que la cartouche qui explique les paramètres, valeur de retour et exception cela n'est pas vraiment concerné...

Mon contexte = multi-projet/multi-équipe pour l'industrie médical et on ne livre pas au client de classe .java des modules oui mais executable donc c'est plus après pour faire de l'intégration que du développement et les évolutions oui mais cela prends du temps dans ce secteur (nouveau en même temps avant j'étais dans une usine à gaz )

[gl]

Tu n'as pas l'air sensible au problème d'interpretation lorsqu'il s'agit de commentaire purement du domaine fonctionnel

Oh que si je suis sensible au problème d'interprétation. Mais il n'y a pas de lien direct avec les commentaires.
C'est une problématique totalement transverse qui se retrouve certes dans la rédaction de commentaires, mais également dans la rédaction de tous les documents du projet, dans le choix des noms de fonctions et variables, dans les réunions et discussions avec les autres intervenants, bref à chaque étape d'un projet

[hegros]

Oh que si je suis sensible au problème d'interprétation. Mais il n'y a pas de lien direct avec les commentaires.

On dirait pas à t'écouter le commentaire que tu as écris il y a 10 ans sera interpreté de la même façon par une autre personne dans 10 ans. Dans ce cas bravo j'aimerais bien le lire ce commentaire.

[gl]

On dirait pas à t'écouter le commentaire que tu as écris il y a 10 ans sera interpreté de la même façon par une autre personne dans 10 ans. Dans ce cas bravo j'aimerais bien le lire ce commentaire.

Je n'ai jamais dit ça. J'ai dit que certes le problème existait pour les commentaires mais existait également pour l'ensemble de la documentation, pour le choix des noms de fonctions/variables et d'une manière générale pour toute communication. Je le répète c'est une problématique transverse.
Et au passage, il n'est pas nécessaire d'attendre 10 ans, une mauvaise interprétation peut se produire au bout de 10 minutes.


Ce n'est pas très honnête de ta part d'extraire une courte citation et de la sortir totalement de son contexte pour prêter à des personnes une pensée qui n'est pas la leur.
N'as-tu donc aucun argument pour justifier tes choix que tu en es réduit à détourner les propos des autres ?

[hegros]

Non du tout tu m'accuses à tords

En plus oui l'interprétation relève de la communication plus particulièrement de l'écoute, c'est donc un problème transverse, au moins sur cela nous nous entendons et on mesure mieux la problèmatique.

En plus comme tu dis cela concerne tout les documents sauf que ceux du projet ne sont pas autant et aussi lu que le code source.

[gl]

En plus comme tu dis cela concerne tout les documents sauf que ceux du projet ne sont pas autant et aussi lu que le code source.

Alors là je n'en suis pas certain. Ils ne sont pas lu par les mêmes personnes je veux bien mais qu'ils soient moins lu, je ne m'avancerais pas (à priori, le manuel utilisateur d'une application est lu par davantage de personne que le code source).

En outre, l'impact d'une mauvaise interprétation d'un document peu lu peut être tout aussi impactant, parfois plus, que la mauvaise interprétation d'un document énormément lu. Par exemple, la mauvaise interprétation des spécifications ou des documents de conception par le développeur peut être très pénalisant, surtout si c'est le même développeur qui rédige les tests unitaires correspondant.

Enfin dans un document relu souvent et par plusieurs personnes, les ambiguïtés sont généralement assez rapidement remarquées et levées.

Ce dernier point, je l'admet bien volontiers, n'est pas toujours (voire rarement) vrai concernant les commentaires et le choix des noms dans le code source (probablement par manque de variété dans le profil, et donc la sensibilité, des différents lecteurs).

[hegros]

Ce sondage prendrait plus d'interet si ceux qui votent oui donne un exemple après tout il y a forcément plusieurs formes d'expression ? des bonnes et des moins bonnes, utiles et inutiles.

[hegros]

Je n'ai jamais dit ça. J'ai dit que certes le problème existait pour les commentaires mais existait également pour l'ensemble de la documentation, pour le choix des noms de fonctions/variables et d'une manière générale pour toute communication. Je le répète c'est une problématique transverse.

D'accord tu reconnais alors que les commentaires ont une date de péremption ou alors qu'ils vont subir énormément de changement. Lorsqu'on pense qu'il y a une règle de 1/3 de commentaire ne penses-tu pas que cela à un coût beaucoup plus important de faire évoluer le code et le commentaire qui va avec et que finalement le commentaire est assez volatile.

Et au passage, il n'est pas nécessaire d'attendre 10 ans, une mauvaise interprétation peut se produire au bout de 10 minutes.

Cela a un impact aussi sur le coût. Un commentaire mal interprété et tu as toute une équipe de développement qui part sur une fausse piste ? Mieux vaut ne rien savoir du commentaire plutôt qu'il amène sur une fausse piste non ?

Ce n'est pas très honnête de ta part d'extraire une courte citation et de la sortir totalement de son contexte pour prêter à des personnes une pensée qui n'est pas la leur.
N'as-tu donc aucun argument pour justifier tes choix que tu en es réduit à détourner les propos des autres ?

J'espère que pour le coup les citations sont pas tronquées et que mes arguments te semblent à la hauteur d'une telle anerie

[gl]

D'accord tu reconnais alors que les commentaires ont une date de péremption ou alors qu'ils vont subir énormément de changement.

Oui, ils ont une "date de péremption" qui au minimum la même que celle du code auxquels ils se rapportent. Et subiront potentiellement des changements lorsque le code concerné change, ce qui somme tout relativement rare dans le cas des commentaires d'en-tête.

Lorsqu'on pense qu'il y a une règle de 1/3 de commentaire ne penses-tu pas que cela à un coût beaucoup plus important de faire évoluer le code et le commentaire qui va avec et que finalement le commentaire est assez volatile.

Ce n'est pas moi qui ai parle de la règle des 1/3 de commentaires et je n'ai jamais prétendu être d'accord avec cette règle, au contraire.
Le coût nécessaire pour faire évoluer est certes plus important que s'il n'y avait pas de commentaire, mais pas beaucoup plus si les commentaires sont judicieux.
Le commentaire est-il volatile ? Pas plus que le code auquel il se rattache.

Cela a un impact aussi sur le coût. Un commentaire mal interprété et tu as toute une équipe de développement qui part sur une fausse piste ? Mieux vaut ne rien savoir du commentaire plutôt qu'il amène sur une fausse piste non ?

Mais ne vaut-il pas mieux un commentaire qui évite une fausse piste ou un long processus essai/erreur que pas de commentaire ?

Tu pars du principe que puisqu'un commentaire peut être mal interprété il ne faut pas en mettre mais, de mon expérience, les commentaires (intelligent j'entends) évitent plus d'erreur qu'ils n'en créent. Et lorsqu'ils sont à l'origine d'une erreur c'est bien souvent qu'ils étaient incomplets.
Doit on supprimer tout commentaire car parfois ils sont à l'origine d'erreur sans se préoccuper de toutes celles qu'ils évitent ?

Petite analogie (une peu foireuse comme toute comparaison), doit-on supprimer les ceintures de sécurité dans les voitures sous prétexte que quelques personnes meurent à cause d'elle bien qu'à côté elles sauvent un nombre bien plus important de vies ?

[hegros]

Le coût nécessaire pour faire évoluer est certes plus important que s'il n'y avait pas de commentaire, mais pas beaucoup plus si les commentaires sont judicieux.

Nous sommes alors d'accord pour dire que les commentaires ont peu d'effet positif sur la maintenance quand on sait que cela représente 70% du temps d'un cycle de vie logiciel et des coûts on pouvait en espérer autrement pour toute la machinerie qui est mis en route derrière pour générer la documentation et le suivi du versionning.

Par rapport à ce qu'explique Garulfo sur le problème de coût de maintenance probablement que les défauts de commentaires ne devraient pas atteindre une part immense en fait je n'en sais rien il doit y avoir des graphiques qui l'expriment.

[gl]

Nous sommes alors d'accord pour dire que les commentaires ont peu d'effet positif sur la maintenance quand on sait que cela représente 70% du temps d'un cycle de vie logiciel et des coûts on pouvait en espérer autrement pour toute la machinerie qui est mis en route derrière pour générer la documentation et le suivi du versionning.

Non, je ne suis pas d'accord avec ce point. En effet :

• D'un côté il faut maintenir et mettre à jour les commentaires durant la maintenance. Ce qui a effectivement un coût mais pas très important.
• D'un autre côté, le but des commentaires intra-code est justement de faciliter le travail du mainteneur et de limiter les risques de régression. Ici on a bien un gain qui compense largement la perte (si ce n'est pas le cas, il y a effectivement un problème, par exemple profusion de commentaires inutiles).
• Quand aux commentaires en en-tête de fonction, ils représentent un gain de temps pour l'utilisation, pas pour la maintenance mais d'un autre ils ne sont pas sensé évoluer dans la phase de maintenance.

[Chatanga]

J'ai répondu "non" mais j'aurai répondu "oui" si la question posée avait été : "les commentaires peuvent-ils être utiles dans le code ?". C'est juste histoire d'avoir un vrai résultat de sondage plutôt qu'un résultat d'élection digne d'une république babanière

Pour moi, un commentaire ne doit pas décrire ce que fait un élément de code sauf si cet élément de code est mal écrit (et donc difficile à comprendre) et qu'il n'est pas possible de le réécrire. Dans ce cas là, je parle de commentaires factuels. Par exemple, quand j'ai à reprendre un code existant, j'ai l'habitude d'écrire des tas de commentaires factuels dans le code qui disparaitront au fur et à mesure du refactoring si ce dernier est envisageable. Alternativement, quand j'écris directement du code, je factorise naturellement chaque commentaire factuel en une méthode et ses paramétres en structures de données complexes (du moins quand je suis bien révéillé).

Idéalement et c'est pour moi un motif de satisfaction qu'en j'y arrive, mon code s'articule en deux étapes : construction d'une grammaire (faite de méthodes et de classes) adaptée à mon problème à l'aide des briques polyvalentes du langage et expression du problème et de sa solution dans cette grammaire. Le résultat est naturellement lisible sans nécessité d'être paraphrasé.

Donc, les commentaires factuels perdent naturellement leur utilité quand un code est bien écrit. Il existe néanmoins des commentaires pour tout le reste : souligner au lecteur certaines parties du code significatives (une section critique, une exécution couteuse en temps, une non-portabilité à envisager), détailler le contexte (à quoi servira en pratique telle donnée construite à tel endroit, la raison d'une approche plutôt qu'une autre tout aussi valide à tel autre endroit) et ainsi de suite. L'élément commun à tous ces commentaires est à mon sens l'intention pédagogique (et c'est pour ça qu'ils sont difficules à écrire pour celui qui crée un code et qui le connait intimement). Alternativement, dans le cas où seule l'interface d'une méthode est disponible, la vertue pédagogique d'un commentaire devient indispensable pour un lecteur qui n'a pas accès à son implémentation (un peu comme s'il ne savait pas en lire le langage).

On pourrait comparer un code sans commentaires à un livre de mathématique constitué uniquement de formules. Ce dernier serait facile à faire évoluer, resterait compréhensible (sans perte d'information en tout cas) pour une personne le lisant avec soin en connaissant les concepts utilisés pour en exprimer de nouveaux mais il n'aurait sans doute pas les faveurs des étudiants. D'un certaine manière, il sera toujours supeflu d'utiliser des commentaires pour reformuler un code en langue naturelle, évoquer une analogie à propos d'une méthode, donner des mini-exemples d'utilisation dans un code. Ca reste néanmoins des aides plus qu'appréciables pour les gens devant reprendre un code donné, un bon moyen de leur faire gagner du temps et les amener rapidement et en douceur à comprendre son travail.

[millie]

On pourrait comparer un code sans commentaires à un livre de mathématique constitué uniquement de formules.

Oui, mais des formules incomplètes (notamment qui ne disent pas exactement dans quelle mesure la formule est applicable) et donc fausse.

Par exemple, la "formule" :
Somme(k^q, k=1 à n) = (1-q^(n+1))/(1-q) est totalement fausse... car incomplète.

Un équivalent de code sans commentaire serait :

Code :

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

1
2
3
4
sommeGeometrique(Entier strictement positif n, Réel q) {
  retourner (1-q^(n+1))/(1-q);
}

me semble pas du tout adapté car la fonction est fausse pour une certaine partie des valeurs que peut prendre q.

Alors que celui-ci, si met en garde la personne utilisant la fonction :

Code :

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

1
2
3
4
5
6
7
/*
 * Retourne la somme de 1 à n de k^q avec q différent de 1
 */
sommeGeometrique(Entier strictement positif n, Réel q) {
  retourner (1-q^(n+1))/(1-q);
}

Ici, la précondition (q!=1) est très simple. Mais il pourrait y avoir des préconditions nettement plus complexe (q pourrait valoir toutes les valeurs sauf si gamma(q) est transcendant où je sais pas quoi avec gamma = la fonction d'Euler))

[Chatanga]

Si on prend cet exemple précis, une bonne manière de le coder aurait été pour moi d'écrire (sachant qu'un mauvais code aurait requis un tel commentaire) :

Code :

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

1
2
3
4
5
sommeGeometrique(Entier n, Réel q) {
  preCondition (n > 0 );
  preCondition (q != 1 );
  retourner (1-q^(n+1))/(1-q);
}

Alors effectivement l'information n'apparaît pas dans le nom de la fonction mais on peut considérer que c'est une précision en terme de définition qui est ici clairement lisible dans le corps de la fonction. Ce n'est donc pas un incomplétude fondamentale lié au langage et ce défaut d'informations aurait très bien pu se retrouver dans un (mauvais) bouquin math.

Ce qui n'apparaît pas par contre c'est la complexité en temps d'exécution en fonction de n, ni un rappel de ce que signifie le terme géométrique en mathématique qui peut ne rien évoquer chez un lecteur profane.

[millie]

Faut-il qu'il est une notion de précondition dans le langage. Et tous les langages les plus utilisés n'en ont pas (C+, C++, Java, C# etc.) D'où la nécessité de le faire apparaitre ailleurs.

Et les quelques langages où l'on peut définir une précondition reste très simple dans la définition des préconditions (il va être impossible de décrire quelque chose comme : q est un réel tel que gamma(q) est transcendant etc.). Pour les quelques langages qui pourront définir de telle précondition (du type PVS), il sera alors obligé de définir gamma, ce que signifie transcendant etc., alors qu'un simple commentaire permet de ne pas tout définir)


Après, un bouquin de maths qui n'indique pas ce cas là, autant le dire, il est pourri

EDIT : Par contre, si tu considères les préconditions, le détail des erreurs et le détails des exceptions comme ne faisait pas partie des commentaires, alors je parle dans le vide

[hegros]

J'ai répondu "non" mais j'aurai répondu "oui" si la question posée avait été : "les commentaires peuvent-ils être utiles dans le code ?".

oui puis c'est plus facile de voter oui sans argumenter que l'inverse et comme il n'y a aucune pré-condition quand à l'état de code forcément avec ce qu'on lit habituellement la réponse ne peut-être que oui


Et je ne peux qu'être d'accord avec ta remarque sur l'écriture de code avec un langage naturel qui rend finalement superflu tout commentaire c'est lié à la génération de langage et c'est vrai qu'aujourd'hui c++,java et consort n'en font pas parti..


milie les pré-condition dans les langages de programmation ce sont les bibliothèques avec des assertions non ? Tu veux dire qu'elles ne sont pas très développées (existantes) pour les mathématiques ?

[millie]

milie les pré-condition dans les langages de programmation ce sont les bibliothèques avec des assertions non ? Tu veux dire qu'elles ne sont pas très développées (existantes) pour les mathématiques ?

En fait, il y a 2 cas pour gérer les préconditions.

Soit il y a une vérification des valeurs passées (dans ce cas, il faut être au courant du type d'erreur qui se produit si une mauvaise valeur est passée)
=> il y a des limitations au niveau de l'utilisation des préconditions (peut être difficile à écrire en langage informatique, voir quasi impossible), mais au moins, la vérification se fait mais il peut y avoir un surcoût éventuel (si la vérification est complexe notamment)

Soit la précondition n'est qu'une information
=> il n'y a aucune limitation, on peut se permettre de donner des infos textuels du type ("u réel qui n'est pas la racine 13ème d'un nombre entier"). Par contre, il n'y a aucune vérification.

Soit elle peut être des 2 types


Dans les 2 cas, si le langage n'est pas prévu pour :
- les outils du type javadoc n'extrait pas les assertions et donc la génération de la documentation ne donne aucune indication là dessus (à moins de passer par des tags, mais cela ne marchera que pour des préconditions informatives )
- La signature de la méthode ne rend pas compte de ça (et donc il est nécessaire d'aller voir dans le code (les EDI permettent en général de voir la documentation des méthodes/fonctions sans avoir besoin d'aller voir le code, donc c'est un peu dommage)). Je travaille beaucoup en Java (malheureusement ?), et les API sont souvent livrés avec la javadoc provenant du code, ce qui fait qu'il n'est pas nécessaire d'aller voir dans le code de l'API (normalement).

En revanche, si le langage est prévu pour, en général :
- les préconditions sont affichés dans la documentation générée
- les préconditions sont liées à la signature de la fonction
Dans ce cas, pas besoin de documenter dans le code ces points.

Si vous considerez ces informations pas comme des "vrais" commentaires, alors j'ai parlé dans le vent