Discussion :

[Invité]

Des variable n, m, et autres sont très bien lorsqu'il s'agit de présenter une formule mathématique, mais il est fortement conseillé de choisir des termes bien plus explicites dans le code.

Explicites pour qui? Quand on documente du code, on le fait pour des gens qu'on ne connait pas, qui interviendront dans des années, sur un code qui aura évolué, avec des "bonnes pratiques" qui n'auront peut être plus grand chose à voir avec les vaches sacrées actuelles...

Le langage mathématique a l'avantage d'être très standardisé, d'évoluer assez lentement, et d'avoir été vu par à peu près tous les programmeurs. Si dans un code tu vois des i et des j, tu devines qu'il s'agit d'indices. Pareillement, des positions représentées par des r, theta et phi (on des angles psi, phi, theta) sont très claires pour quiconque a un peu de culture mathématique, probablement plus que l'explication en franglais de cuisine d'un développeur qui voudra "faire expressif".

A mon avis, dès qu'on est sur un algorithme un tant soit peu matheux, on a tout intérêt à conserver aux variables leur "nom mathématique". Et plus généralement, il vaut souvent mieux s'appuyer sur des conventions à peu près stable de nommage de variables, quitte à ce que les noms ne soient pas trop précis.

Plutot que d'appeler tes variables Q, N et D, pourquoi ne pas les appeler quotient, numerateur et diviseur Après tout, c'est ce que tes variables représentent non

C'est ce que ces variables représentent aujourd'hui, mais le code risque d'évoluer et le nom de variable peut devenir tout aussi faux qu'un commentaire.

Il est typique, en 2D, d'appeler x l'abscisse (la coordonnée horizontale), et y l'ordonnée. Mais c'est souvent une mauvaise idée de les renommer en position_horizontale et position_verticale. Il suffit d'une évolution du code, qui permet les rotations, pour que cela devienne illisible. Pareil avec les tableaux, indice_ligne, indice_colonne est très souvent une mauvaise idée : il suffit d'une transposition...

Et quand tu te retrouves à débuguer ce genre de code expressif, où les classes ont été "bien nommées" au début, par quelqu'un qui ne comprenait pas tout à fait bien la logique d'ensemble, où les position_horizontale n'en sont pas, où le champ code_invariant est en fait variable, ou "net" veut dire "brut" et inversement... tu te dis que tu aurais préféré du Fortran ou du Cobol.

Le code très expressif qui s'autodocumente, c'est souvent un fantasme de jeune développeur, et au cauchemar de vieux mainteneur...

Francois

[g.Arnaud]

C'est ce que ces variables représentent aujourd'hui, mais le code risque d'évoluer et le nom de variable peut devenir tout aussi faux qu'un commentaire.

Si le nom d'une variable ne représente plus la même chose, c'est qu'elle doit changer de nom ou alors ajouter une nouvelle variable.

Et quand tu te retrouves à débuguer ce genre de code expressif, où les classes ont été "bien nommées" au début, par quelqu'un qui ne comprenait pas tout à fait bien la logique d'ensemble, où les position_horizontale n'en sont pas, où le champ code_invariant est en fait variable, ou "net" veut dire "brut" et inversement... tu te dis que tu aurais préféré du Fortran ou du Cobol.

S'il y a un problème de compréhension, les commentaires et la doc risquent d'être au moins aussi faux que les noms de variables.

[r0d]

Si le nom d'une variable ne représente plus la même chose, c'est qu'elle doit changer de nom ou alors ajouter une nouvelle variable.

Je plussoie.
D'ailleurs, cette façon de voir les choses m'amène souvent à faire des choses que d'autres programmeurs ne comprennent pas. Par exemple, pour un algorithme, j'ai besoin d'une structure qui représente un vecteur d'entier. Une simple structure qui contient deux entiers x et y. Et bien plutôt que d'utiliser une structure qui existe déjà, comme Point ou std::pair<int,int>, je préfère définir une nouvelle structure Vector.

[Matthieu Vergne]

De ce que je vois dans ce sujet, il y a grosso-modo deux approches (corrigez-moi si je me trompe) :
- une qui croit en l'expressivité d'un code bien conçu, ce qui justifierait la quasi-absence de commentaires (qu'on garde pour des cas très particuliers où il faut expliquer plus que le "comment")
- l'autre qui n'y croit pas et qui prône le langage naturel comme base de la compréhension du code

L'avantage du premier est que, si il y a moyen d'utiliser un langage expressif (proche du langage naturel, comme les if, while, etc. mais probablement pas comme le Lisp par exemple), il est possible de s'éviter le double travail imposé par les commentaires, à savoir les tenir à jour tout comme le code (je rappelle qu'on ne parle pas de documentation, qui peut-être bien plus stable). L'inconvénient est que, après un temps, le langage peut changer, ou tout simplement on peut-être intéressé de retranscrire le code d'un langage à un autre, et là comprendre le code devient une gageüre. Je pense notamment au C++ qui, quand je m'y suis mis il y a un paquet d'années, faisait valoir certaines structures et patterns plus que d'autres, avec des conventions d'écriture spécifiques. étant passé sur Java, je n'ai pas touché à du C/C++ depuis belle lurette, et aujourd'hui quand je reprends des codes C++ récent je suis perdu, car de nouveaux outils sont sortis et ont pris le pas sur les anciennes habitudes. On touche donc à la stabilité du langage, qui est primordiale pour la maintenance sur le long terme.

Le second cas prend la contre-partie : on se base sur un langage relativement stable dans le temps (langage naturel) qui, si la spec ne change pas, ne devrait pas changer. L'inconvénient ici est le manque de formalité de la langue, qui fait qu'on peut exprimer une chose de 1001 manières différentes, en plus qu'il faut choisir ce qu'on dit et ne dit pas (donc ce qu'on considère évident ou non), et c'est autant de choses qui prennent le pari que le futur mainteneur l'interprètera de la bonne manière.

Autrement dit, là où les "anti-commentaires" parient sur un effort de conception et le formalisme du code pour s'assurer une bonne compréhension, les "pro-commentaires" parient sur l'expressivité naturelle de la langue et sa stabilité dans le temps. Le problème du premier est la stabilité du langage, qui peut-être réduite et donc perdre son "sens commun" avec le temps, et pour le second c'est la possibilité de mal interpréter, car contrairement au code une phrase en langue naturelle peut avoir objectivement plusieurs significations et être incomplète.

Donc en soit, les deux se valent, chacune faisant un pari donné.

[koala01]

Code :

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

1
2
3
4
5
6
7
8
9
10
11
/* nous ne calculeront jamais au delà de 10! */
function factoriel(int i) {
/* 
     uint res = 1;
     for(uint j = 2;j<i;j++)
     {
          res *= j;
     }
     return res;
*/

Que penses tu du terme "précondition" dans le cartouche

Code :

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

1
2
3
4
  return i * i; // on obtient de meilleur résultats en se basant sur un carré
// todo: refactoriser le nom de la fonction ou revenir sur un factoriel
}

Le premier commentaire est inutile : si on a décidé de renvoyer le carré d'une valeur, c'est qu'on a ses raisons.
Quant au todo pourrait tout aussi bien se trouver dans le cartouche.

Ce serait d'ailleurs préférable, étant donné que cela permettrait à "n'importe qui" de savoir qu'il y a peut etre une amélioration à effectuer

car je persiste à dire qu'un code toujours propre ça n'existe pas, même avec

Autrement dit, là où les "anti-commentaires" parient sur un effort de conception et le formalisme du code pour s'assurer une bonne compréhension, les "pro-commentaires" parient sur l'expressivité naturelle de la langue et sa stabilité dans le temps. Le problème du premier est la stabilité du langage, qui peut-être réduite et donc perdre son "sens commun" avec le temps, et pour le second c'est la possibilité de mal interpréter, car contrairement au code une phrase en langue naturelle peut avoir objectivement plusieurs significations et être incomplète.

Donc en soit, les deux se valent, chacune faisant un pari donné.

Je ne suis pas "anti commentaire", je suis plutôt attaché à des commentaires stables dans la durée.

C'est pour cela que ma première intervention était de dire "faisons un cartouche et mettons y tout ce qu'il est possible d'y mettre comme information stable".

Je me suis même fendu d'une liste qui reprend ce que je considère comme information stable à savoir

1. une breve description du service rendu / du comportement
2. (si besoin) une description plus détaillée voir un rappel du principe utilisé
3. la description et l'utilité des différents paramètres
4. une description de la valeur renvoyée (s'il échoit) voir les conditions pour qu'elle soit renvoyée, ainsi que la valeur renvoyé (s'il échoit, toujours) si la condition n'est pas respectée
5. les pré conditions / post conditions / invariants à respecter
6. les exceptions éventuellement levées et les conditions dans lesquelles elles le sont
7. Le cas échéant, la liste des "autres fonctions" portant sur le même thème

à laquelle (je les avais oubliés ceux là) on peut rajouter des informations éventuelle de chose à faire (todo) ou de déprécation de la fonction.

Je ne plaide pas pour l'absence totale de commentaires, je plaide pour des commentaires qui soient efficaces et suffisamment stables dans le temps pour éviter le risque de se retrouver avec deux sources d'informations désynchronisées.

L'interface (le nom des fonctions, leurs paramètres et valeur de retour, les pré et post conditions, les exceptions éventuellement lancées, ...) est stable dans le temps car il y a peu de chances que l'on décide de changer "ce à quoi sert" une fonction.

Par contre, le code de la fonction n'offre aucune garantie de stabilité, que ce soit suite à des corrections de bug ou (car les "bons principes" de programmation ne sont pas toujours suivis) suite à des évolutions que l'on aura "intégré" au code des fonctions existantes.

On se rend donc bien compte que les commentaires que l'on pourrait envisager de mettre dans le code de la fonction ne valent qu'à partir du moment où ils sont réellement représentatifs de ce que fait réellement le code.

J'ai l'impression que les ardent défenseurs du commentaire dans le code font deux sortes de paris:

1. Soit que le code sera "tellement bon" qu'il ne faudra plus jamais y toucher
2. Soit que les commentaires seront mis à jour à chaque fois que le code sera modifié.

Dans le premier cas, j'aurais envie de dire "mais alors, pourquoi se fendre de commentaires, s'il ne faudra plus le relire "

A moins que l'on pense juste "au suivant" qui viendra et qui voudra comprendre le code (sans le modifier, hein, malheureux!!!), il n'y aurait aucune raison de les mettre

Dans le deuxième cas, je prendrais beaucoup plus facilement le pari inverse et j'aurais beaucoup plus de chance de gagner: l'expérience m'a montré que les commentaires ne sont jamais (aller, disons plutôt "que très rarement" ) mis à jour.
[EDIT] A ce moment là, je préfères prendre mes précautions pour que le code soit compréhensible "par lui même" en veillant à utiliser des noms qui indiquent clairement l'utilité de ce qu'ils représente

[Matthieu Vergne]

Ton cartouche c'est de la documentation, on dit bien depuis le début qu'il faut faire la différence (je l'avais précisé d'ailleurs dans mon dernier post, je ne parlais pas de documentation). Une optimisation particulière du code (par exemple l'utilisation d'une table de hachage pour profiter de l'accès en O(1) au lieu d'une liste chainée en O(n)) n'a rien à faire dans le cartouche, vu que ça concerne certaines lignes précises de la fonction (qu'on pourra changer complètement sans altérer le fonctionnement de base, et donc sans changer le cartouche).

[koala01]

Je me permet ici un "double post" car je voulais te répondre "personnellement"

Explicites pour qui? Quand on documente du code, on le fait pour des gens qu'on ne connait pas, qui interviendront dans des années, sur un code qui aura évolué, avec des "bonnes pratiques" qui n'auront peut être plus grand chose à voir avec les vaches sacrées actuelles...

Le langage mathématique a l'avantage d'être très standardisé, d'évoluer assez lentement, et d'avoir été vu par à peu près tous les programmeurs. Si dans un code tu vois des i et des j, tu devines qu'il s'agit d'indices. Pareillement, des positions représentées par des r, theta et phi (on des angles psi, phi, theta) sont très claires pour quiconque a un peu de culture mathématique, probablement plus que l'explication en franglais de cuisine d'un développeur qui voudra "faire expressif".

Si tu relis mon intervention, la première notion que j'introduis est celle d'un domaine bien spécifique pour laquelle je dis explicitement que cela ne me pose pas de problème si les variables que l'on utilise ont une sémantique particulière.

J'aurais (cela aurait sans doute été plus clair) pu dire que, s'il existe des conventions propres à un domaine spécifique, il faut, bien sur, suivre les conventions de ce domaine (il y a quelques mois, j'ai fait la morale à ce sujet à un type qui inversait les conventions pour les coordonnées )

A mon avis, dès qu'on est sur un algorithme un tant soit peu matheux, on a tout intérêt à conserver aux variables leur "nom mathématique". Et plus généralement, il vaut souvent mieux s'appuyer sur des conventions à peu près stable de nommage de variables, quitte à ce que les noms ne soient pas trop précis.

j'irais même jusqu'à dire que les conventions de nommages doivent être "le plus stable possibles"

Cependant, il arrive régulièrement que l'on doive traverser différents domaines, qui utilisent différentes conventions.

C'est ce que ces variables représentent aujourd'hui, mais le code risque d'évoluer et le nom de variable peut devenir tout aussi faux qu'un commentaire.

Dans le cadre "global" du projet peut etre, mais pas dans le cadre stricte de la fonction dans laquelle ces variables sont définies.

Il est typique, en 2D, d'appeler x l'abscisse (la coordonnée horizontale), et y l'ordonnée. Mais c'est souvent une mauvaise idée de les renommer en position_horizontale et position_verticale. Il suffit d'une évolution du code, qui permet les rotations, pour que cela devienne illisible.

sur ce point, nous sommes bien d'accord, et c'est bien pour cela que j'avais introduit cette notion de "domaine spécifique"

Pareil avec les tableaux, indice_ligne, indice_colonne est très souvent une mauvaise idée : il suffit d'une transposition...

Là, par contre...

Si tu as une matrice, tu veux accéder à l'élément qui se trouve à la position ligne, colonne.

tu te fous pas mal de savoir si c'est la transposée ou meme de savoir si ta matrice est construite de manière à prendre la ligne ou la colonne comme premier indice.

Tu veux juste que ta fonction indexAt(ligne, colonne) te renvoie l'élément correct.
(c'est aussi d'ailleurs vrai lorsque tu veux récupérer l'abscisse d'une coordonnée après une rotation: tu veux que x corresponde bel et bien à l'abscisse et non à l'ordonnée)
En utilisant des variable nommées ligne et colonne au lieu de i et de j, ton code reste expressif (dit exactement ce que tu veux), dans un contexte donné qui est celui de la fonction dans laquelle tes variables sont définies

Et quand tu te retrouves à débuguer ce genre de code expressif, où les classes ont été "bien nommées" au début, par quelqu'un qui ne comprenait pas tout à fait bien la logique d'ensemble, où les position_horizontale n'en sont pas, où le champ code_invariant est en fait variable, ou "net" veut dire "brut" et inversement... tu te dis que tu aurais préféré du Fortran ou du Cobol.

Là, il faut "taper sur les doigts" de celui qui a si mal choisi ses noms

Le code très expressif qui s'autodocumente, c'est souvent un fantasme de jeune développeur, et au cauchemar de vieux mainteneur...

Correctement mis en oeuvre, c'est plutôt un plaisir pour les vieux développeurs.

Maintenant, cela peut sans doute aussi dépendre du langage

[koala01]

Ton cartouche c'est de la documentation, on dit bien depuis le début qu'il faut faire la différence (je l'avais précisé d'ailleurs dans mon dernier post, je ne parlais pas de documentation). Une optimisation particulière du code (par exemple l'utilisation d'une table de hachage pour profiter de l'accès en O(1) au lieu d'une liste chainée en O(n)) n'a rien à faire dans le cartouche, vu que ça concerne certaines lignes précises de la fonction (qu'on pourra changer complètement sans altérer le fonctionnement de base, et donc sans changer le cartouche).

Excuses moi, mais qu'est ce que tu en as a foutre de la complexité de ta fonction

Au pire, tu as deux fonctions bien distinctes et tu indiques (dans le cartouche) les différences qui existent entre ces deux fonctions, afin de permettre à l'utilisateur de choisir "celle qui lui convient le mieux" (parce que ca correspond à la documentation "utilisateur" de ces fonctions).

Au mieux, tu auras pris cette décision suite à un bench, mais c'est l'ensemble de ta structure qui aura été modifiée (ce qui pourrait avoir un impact sur l'interface), mais la raison de ce changement apparaitra plus au niveau du système de gestion de version concurrente qu'au niveau du code (et, "si tout va bien" au niveau des spécifications / de l'analyse)

[Neckara]

Excuses moi, mais qu'est ce que tu en as a foutre de la complexité de ta fonction

Je pense qu'il serait un peu suicidaire d'utiliser un algorithme en O(n!) sur une liste de plus de 1 000 éléments par exemple


On peut faire tourner un algorithme pendant 2 semaines sur des super-calculateurs sur une portion infime des données à traiter sans en arriver au bout.

Et réussir en à peine quelques minutes à avoir tous les résultats sur la totalité des données sur un petit ordinateur portable juste en ayant une complexité bien plus faible.

La STL par exemple, renseigne les complexité des fonctions.

[koala01]

Je pense qu'il serait un peu suicidaire d'utiliser un algorithme en O(n!) sur une liste de plus de 1 000 éléments par exemple


On peut faire tourner un algorithme pendant 2 semaines sur des super-calculateurs sur une portion infime des données à traiter sans en arriver au bout.

Et réussir en à peine quelques minutes à avoir tous les résultats sur la totalité des données sur un petit ordinateur portable juste en ayant une complexité bien plus faible.

La STL par exemple, renseigne les complexité des fonctions.

Je te l'accorde, mais cela n'est qu'un "détail d'implémentation".

Le fait est que si tu passes d'un algorithme ayant une complexité en O(n) (voir en o(n!) ) à un algorithme ayant une complexité en O(1) ou en O(n/2), c'est de toutes manière "tout ce qui touche à cet algorithme" qui sera remis en cause.

Cela peut se faire au niveau d'une fonction (en décidant de remplir une hashmap au lieu d'une liste sur base des données reçues), au niveau d'une structure de données en décidant de changer le type de la collection ou même au niveau global de l'application en décidant de transmettre un type de collection plutôt qu'un autre, mais le fait de justement utiliser un type de collection plutôt qu'un autre "suffit" à savoir quelles en sont les forces et les faiblesses.

Je ne vois pas en quoi il est utile de préciser que telle ou telle partie de l'algorithme ressort de telle ou telle complexité dans un commentaire, cette information étant donnée d'elle meme par le type de la collection utilisée

[Invité]

Je ne vois pas en quoi il est utile de préciser que telle ou telle partie de l'algorithme ressort de telle ou telle complexité dans un commentaire, cette information étant donnée d'elle meme par le type de la collection utilisée

Ca ne dépend pas forcément de la collection.

Un petit exemple, sur de gros vecteurs, le tri "à tout faire" le plus rapide est quicksort. Mais si ton vecteur est à peine désordonné (cas très fréquent en pratique) c'est insertsort, imbattable dans ce cas, mais à proscrire (car quadratique) sur un fichier très désordonné. Si en revanche tu as peu de valeurs différentes (encore un cas courant), il y a des alternatives nettement plus efficaces. Le choix de l'algorithme ne dépend pas du conteneur, mais de son contenu, et c'est typiquement une décision à laisser au programmeur.

Tu as pas mal de choix de ce type dès que tu fais du calcul numérique. Souvent tu auras un algo adapté à un type de données, et à proscrire dans les autres cas, avec toutes sortes de situations grises au milieu. Avoir cette information dans le cartouche est utile.


Un autre cas, assez important, est celui où le programme va devoir tourner sur des volumétries différentes (par exemple plus de données, ou plus de champs, ou...). Connaitre les ordres des différentes fonctions clefs permet de savoir à l'avance où les problèmes vont se poser, bref, ce qu'on peut réutiliser, et ce qu'il vaut mieux refaire.

Francois

[koala01]

Ca ne dépend pas forcément de la collection.

Un petit exemple, sur de gros vecteurs, le tri "à tout faire" le plus rapide est quicksort. Mais si ton vecteur est à peine désordonné (cas très fréquent en pratique) c'est insertsort, imbattable dans ce cas, mais à proscrire (car quadratique) sur un fichier très désordonné. Si en revanche tu as peu de valeurs différentes (encore un cas courant), il y a des alternatives nettement plus efficaces. Le choix de l'algorithme ne dépend pas du conteneur, mais de son contenu, et c'est typiquement une décision à laisser au programmeur.

Tu as pas mal de choix de ce type dès que tu fais du calcul numérique. Souvent tu auras un algo adapté à un type de données, et à proscrire dans les autres cas, avec toutes sortes de situations grises au milieu. Avoir cette information dans le cartouche est utile.

Dans le cartouche, oui...

Mais non à l'intérieur du code

Un autre cas, assez important, est celui où le programme va devoir tourner sur des volumétries différentes (par exemple plus de données, ou plus de champs, ou...). Connaitre les ordres des différentes fonctions clefs permet de savoir à l'avance où les problèmes vont se poser, bref, ce qu'on peut réutiliser, et ce qu'il vaut mieux refaire.

Encore un fois, ce sont des informations qui n'ont rien à faire dans le code en lui-même, car ce sont des informations de "documentation générale".

Dés lors, ou vas tu les mettre
Au début de chaque fonction
dans le cartouche de chaque fonction
A chaque fois que tu fais appel à une fonction au départ d'une autre

Tu ne crois pas qu'il est beaucoup plus intéressant d'avoir, dans la documentation de ton projet une section "ordre des différentes fonctions clefs", mise à jour "en cas de besoin" (donc, a priori, très rarement) plutôt que d'avoir ce genre d'information éparpillée dans le code

[Matthieu Vergne]

Je vais reprendre les termes qui m'ont été soumis :

Mais qu'est-ce que tu en as à foutre que ce soit pour l'utilisation d'une table de hachage ou pour autre chose ?

Ce que je voulais soulever, c'est que si dans ton code, tu utilise quelque chose de particulier en lieu et place d'autre chose sous prétexte que ça a des propriétés plus intéressantes, c'est ça que tu vas commenter, et pas mettre dans le cartouche/la doc. Je ne parle pas de l'algo de la fonction complète, mais d'une partie de la fonction qui n'est pas importante en soit vis-a-vis de la fonction complète. Par exemple, tu as une fonction qui cherche les informations communes de plusieurs personnes pour faire un descriptif de groupe. L'objectif de la fonction est donc de retrouver les informations de chaque personne, puis de comparer et de garder ce qui est commun, et enfin de créer une description et d'y mettre les données trouvées. Ici, tu te fiches pas mal des détails sur comment tu vas retrouver les données. Tu sais que tu as une liste de personnes avec leurs données que tu vas parcourir, point, quelle technique tu vas utiliser importe peu car ce n'est pas l'objectif principal de la fonction (ou sinon tu vas aussi dire comment tu fais chaque addition dans une fonction de calcul ?). Si au départ tu utilises par exemple une liste chainée, puis tu vois par un benchmark que finalement c'est long, tu vas remplacer ça par une table de hachage, mais l'algo de la fonction reste le même, c'est une modif propre à l'implémentation, l'algo abstrait complètement cette partie. Et dans ta fonction, tu peux ajouter le commentaire :

// on utilise une table de hachage plutôt qu'une liste chainée pour avoir de meilleures performances

C'est là que tu donnes le pourquoi de la table de hachage. Ton algo tu pourrais aussi bien l'utiliser dans une autre appli que tu n'aurais pas besoin de la table de hachage parce que ce serait beaucoup de calcul (hash) pour pas grand chose (petite liste). Il n'y a donc aucun intérêt à mettre ça dans le cartouche, car l'algo est le même, l'objectif est le même, mais l'implémentation est optimisée autrement. Si un jour tu as une implémentation maison qui marche mieux car profite de propriétés spécifiques, tu pourras encore changer le fonction sans altérer le fonctionnement de base.

La doc (cartouche), c'est la perspective boîte noire, le commentaire dans la fonction c'est boîte blanche. Ça ne sert à rien de mettre des spécificités locales à la fonction si elles n'ont pas d'impact notable sur son utilisation, en particulier car c'est la partie variable de l'algo, même en suivant ta logique ce n'est pas la partie stable qui doit se trouver dans le cartouche.

[Invité]

Tu ne crois pas qu'il est beaucoup plus intéressant d'avoir, dans la documentation de ton projet une section "ordre des différentes fonctions clefs", mise à jour "en cas de besoin" (donc, a priori, très rarement) plutôt que d'avoir ce genre d'information éparpillée dans le code

Non. La documentation projet, c'est encore pire que les commentaires. Sur un projet un peu vieux, tu peux être certain qu'elle n'est pas à jour, sauf si elle est produite partir du code (et alors, on est ramené au problème précédent).

Par ailleurs, l'ordre, c'est un paramètre de code, il est assez naturel qu'on le trouve dans le code, au début de la fonction. Mais il peut être utile de le rajouter lors de l'appel, s'il y a un risque. Le seul cas où je ne le ferais pas, c'est quand c'est évident, par exemple, si tu fais une recherche dichotomique, le code est assez caractéristique pour n'avoir rien besoin de préciser.

En fait, je me rends compte en te répondant qu'on ne voit pas les commentaires de la même façon. Pour moi, ce sont des indices que je donne aux suivants (moi éventuellement), pour expliquer des détails, souvent d'implémentation, piégeux. Et dans l'ensemble je commente peu, pour cette raison, trop d'info tue l'info.

Francois

[Paul TOTH]

Dans le cartouche, oui...

tu restes sur tes positions, je resterais sur les miennes.

Mais comme exemple de ma vision des choses, voici un code dont les commentaires me semblent bienvenus -> compiler.cc

[koala01]

tu restes sur tes positions, je resterais sur les miennes.

Mais comme exemple de ma vision des choses, voici un code dont les commentaires me semblent bienvenus -> compiler.cc

Code :

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

1
2
3
4
5
6
7
8
 // We should never arrive here if there is no code object on the
  // shared function object.
  Handle<Code> code(info()->shared_info()->code());
  ASSERT(code->kind() == Code::FUNCTION);

  // We should never arrive here if optimization has been disabled on the
  // shared function info.
  ASSERT(!info()->shared_info()->optimization_disabled());

Tu ne trouve pas que le commentaire fait double emploi avec l'assert

Code :

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

1
2
3
4
5
6
7
8
  // Limit the number of times we re-compile a functions with
  // the optimizing compiler.
  const int kMaxOptCount =
      FLAG_deopt_every_n_times == 0 ? FLAG_max_opt_count : 1000;
  if (info()->opt_count() > kMaxOptCount) {
    info()->set_bailout_reason("optimized too many times");
    return AbortOptimization();

Encore une fois, le commentaire ne fait qu'exprimer ce que le code exprime déjà clairement...

Si l'on vient à modifier le code (pour une raison ou une autre) sans modifier le commentaire...

Et celle que je préfères:

Code :

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

1
2
3
4
5
#ifdef ENABLE_DEBUGGER_SUPPORT
  // Notify debugger
  isolate->debugger()->OnAfterCompile(
      script, Debugger::NO_AFTER_COMPILE_FLAGS);
#endif

Non!!! Sans blague??? je croyais que ca faisait le café moi

PS: je n'ai pas lu tout le code, mais ce sont quelques "perles"

[jouana]

Bonjour,

Je pense que le plus propres c'est un code clair concis (bonne conception), avec une jolie analyse statique du code pour appuyer ça qualité.

Ensuite des commentaires pour la génération d'un doc qui facilitera la recherche d'information, ça évite de lire les sources pour trouver le bout de code qui nous est nécessaire ou pire re-coder une fonction existante.

Et des commentaires pour les cas particuliers ou complexes.

En gros le soucis ce n'est pas le code ou les commentaires mais la rigueur des équipes travaillant sur un projet.

Bonne journée a tous.

[Paul TOTH]

Un autre domaine où les commentaires me semblent indispensables, c'est HTML, CSS et Javascript...vu que le comportement du code est totalement dépendant du navigateur, il n'est pas superflu de préciser que tel cas de figure se produit sur tel navigateur. Chose difficilement prévisible à la seule lecture du code ... sauf à avoir une parfaite connaissance des différences de l'ensemble des navigateurs supportés.

[dragonno]

Pour moi un programme bien écrit a toujours besoin de commentaires, d'abord parce que si le programme est considéré comme bien écrit par son auteur, il se peut qu'il ne soit pas considéré ainsi par un autre programmeur de même niveau ou plus expérimenté.
Ensuite parce qu'un programme commenté est plus facilement compris par des débutants ou des programmeurs moins expérimentés.
Enfin un programme commenté est mieux compris par d'autres bons programmeurs.
Et même l'auteur du programme voit mieux le but et l'ensemble de son programme quand il le retrouve après des années.

Conclusion : Vive les commentaires.

[sekaijin]

...
Et même l'auteur du programme voit mieux le but et l'ensemble de son programme quand il le retrouve après des années.

au développeur qui ne sait pas comment décrire ce que fait une méthode
je dis: ton code est surement trop mal foutu si tu ne peux l'expliquer. il te reste à le re concevoir !

Je pense que souvent lorsqu'on n'arrive pas à exprimer clairement ce qu'on fait il y a de fortes chances pour qu'on l'ait tout aussi mal exprime en le codant.


commenter permet de relire sont code et souvent de l'améliorer.
A+JYT