Discussion :

[gl]

Merci enfin quelqu'un qui trouve un exemple de commentaire sur 15 ans et cela concerne un système d'exploitation soit c'est un domaine de développement à part.

Oui c'est un domaine à part, comme tout autre domaine.

L'informatique n'étant après tout qu'un outil et non une fin en soi, les développements sont nécessairement influencés par les us et pratiques et les contraintes du domaine fonctionnel dans lequel il intervient.

Ce qu'il y a de bien dans un tel "contre-argument", c'est que tu peux le ressortir à chaque fois .

De plus il est open-source est destiné à être lu par des développeurs de tous les coins de la planète contrairement à des logiciels en général d'entreprise qui ont un autre modèle économique que l'open-source (soit probablement la majorité qui nous intéresse quoique cela reste discutable)

Je te renvois à la remarque très pertinente de millie.
Comment veux-tu qu'on puisse te fournir un tel exemple qui ne soit pas open source ?

En plus par rapport au thread initial il n'y a aucun rapport avec ce que tu montres puisque pour rappeler le contexte c'est dans quelle mesure un commentaire rend un code propre hors là il n'y a même pas de code....(enfin le printk.c mais bon...)

au cas où tu ne l'aurais pas compris, il ne s'agit pas de tout le contenu du fichier en question mais juste d'un extrait. Et quelque chose me fait penser qu'il y a également du code dans ce fichier et que ce commentaire sert justement à documenter l'usage d'une partie de ce code (en l'occurrence la fonction sys_syslog)

[souviron34]

Un commentaire qui traverse le temps 10 ans ou 20 ans ou 30 ans est forcément obsolète, inutile ou faux et surtout rarissime quand on sait la durée de vie des logiciels en moyenne...

je ne te comprend pas, mais je sais que tu provoques...

Ce n'est nullement rarissime quun logiciel dure plus de 10 ans.. C'est même plutôt le contraire, dans l'industrie..

Sauf dans "l'industrie du logiciel", qui pousse à la consommation..

Mais une très grosse proprotion des logiciels fabriqués ne le sont pas pour "les jeux" ou "un outil temporaire", mais un outil long terme...

Sans compter les bibliothèques..

Tu veux des commentaires non obsolètes ?

Regarde le code de HTTP (19 ans), les codes du CERN, les codes de biblothèques mathématiques comme Minuit (Fortran) (50 ans d'existence), les codes MPEG (18 ans), XFree (dérivés de X original - 25 ans), etc etc etc...

Il y a 250 millions d'exemples...


Il est bien évident que si on se limite aux programmes Windows, ils sont souvent obsolètes, puisque même l'OS change de version tous les 2 ans, les progs de 6 mois à 1 an...

[hegros]

C'est de ma faute c'est la meilleure celle là. Un système d'exploitation n'a pas le même cycle de vie que les autres logiciels c'est VRAIMENT un cas à part en fait ils ont les plus grands cycles de vie (voir microsoft j'y peux rien moi et linux..)


oui effectivement milie a raison cela va être impossible c'est un peu abusé Allez pour de l'open-source mais comme dis c'est quasi impossible de trouver un commentaire qui voyage dans le temps >10 ans vu la durée de vie des logiciels (en moyenne)

Ca casse un peu les commentaires désolé dés qu'on y touche c'est la crise...

[hegros]

je ne te comprend pas, mais je sais que tu provoques...

Bien vu

Tu veux des commentaires non obsolètes ?
Regarde le code de HTTP (19 ans), les codes du CERN, les codes de biblothèques mathématiques comme Minuit (Fortran) (50 ans d'existence), les codes MPEG (18 ans), XFree (dérivés de X original - 25 ans), etc etc etc...

Le code du CERN le plus vieux est < 10 ans, en moyenne c'est quoi 5 ans ?

Pour Minuit en Fortran premier source déjà l'entête de commentaire mélange explication du code source, distribution de licence GNU blabla et historique des versions. Cela concerne les fichiers .c pour les fichiers .fortran il ne semble pas y avoir de commentaire


Le code MPEG, hors entête de fichier source, il n'y a rien à dire sur les commentaires à la limite souvent 'paraphrasé' et quand c'est trop long le nom de la fonction n'est pas toujours explicite..

Finalement Xfree a l'air plus orienté commentaire intra-code c'est la même qualité de code que MPEG mais en plus explicite soit avec moins de paraphrase de commentaires

Bon c'est après quelques ouvertures de fichiers .c c'est pas une vue d'ensemble et pas très pertinent pour 'casser' les commentaires cela montre surtout que le code explicite nécessite moins de commentaires à vue de pif biensûr...

[gl]

Un système d'exploitation n'a pas le même cycle de vie que les autres logiciels c'est VRAIMENT un cas à part

Le problème c'est qu'il n'y a que des cas à part, chaque domaine à ses spécificités (que ce soit la durée de vie, mais également les contraintes de temps, de disponibilité, de portabilité, de multi-threading/multi-tâche, d'accés concurrent, d'empreinte mémoire, le mode de distribution, ou que sais-je encore).

en fait ils ont les plus grands cycles de vie (voir microsoft j'y peux rien moi et linux..)

Ah! les OS ont les plus grands cycles de vie ! Peux-tu détaillé ton propos à ce sujet ?

oui effectivement milie a raison cela va être impossible c'est un peu abusé Allez pour de l'open-source mais comme dis c'est quasi impossible de trouver un commentaire qui voyage dans le temps >10 ans vu la durée de vie des logiciels (en moyenne)

Et pourtant.

Actuellement, là où je travaille, le développement de certains produits a commencé à la fin des années 80 et même si ces produits ont fortement évolués, certaines portions de code datent de cette époque car il n'a jamais été nécessaire de les retoucher (à part le style un peu désuet -par exemple les déclarations de fonction en style K&R- il n'y a pas de raison de toucher à ce code, il fonctionne bien et remplit son rôle).

Le premier logiciel sur lequel j'ai travaillé il y a maintenant plus de 8 ans (et c'était loin d'être la première version, cette dernière datant de 2 ou 3 ans de plus) existe encore et présente un pourcentage de ligne de code identique à celui présent à l'époque très important (largement plus de la moitié). Et même si objectivement, il mériterait d'être refait (conception bancale dès l'origine, première version codée en dépit du bon sens puis application de patchs plus ou moins bien fait ensuite, etc. Bref loin d'être un code propre), il n'empêche que le code existe encore et qu'il existera encore plusieurs années vu le peu de volonté de le refaire proprement.

P.S.: au passage as-tu des statistiques fiables sur la durée de vie des différents types de logiciel ? Je n'ai jamais rien trouvé de probant à ce sujet.

Ca casse un peu les commentaires désolé dés qu'on y touche c'est la crise...

Non, ce je ne pense pas que ce soit la crise lorsqu'on touche les commentaires.
Personnellement (et vu les remarques de la plupart des autres intervenants je ne dois pas être le seul), j'accepte volontiers toutes critiques constructives et argumentées sur les commentaires que j'ai commis et je suis prêts à faire évoluer ma façon de commenter si ça présente des avantages (elle a d'ailleurs fortement évoluer depuis mes premières lignes de code).

Le problème c'est que tes seuls arguments se résument à : il faut enlever les commentaires car "ça sert à rien", "de toute manière, ils sont forcément périmés" et "c'est trop long à mettre à jour" (je grossis un peu le trait mais le message de fond est bien celui-ci).
Ce qui d'une part ne correspond pas à mon expérience (certains commentaires m'ont déjà bien servis et j'en ai rencontré un nombre important tout à fait à jour) et que d'autre part je ne vois pas d'avantage à ne pas les écrire (à part gagner un peu de temps, temps bien inférieur à celui que des commentaires judicieux[1] m'ont déjà fait gagner).



[1] Une fois encore j'insiste bien sur la notion de commentaires judicieux. En effet des commentaires du style :

Code :

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

int i; /* on déclare un entier i */

Code :

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

i++; /* incrément de i*/

sont bien évidement inutiles et représentent une perte de temps et de lisibilité sans intérêt, et de fait n'ont pas de raison d'exister.

Par contre un commentaire du style des deux-trois exemple fournis ou de celui-ci

Code :

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

1
2
3
4
5
6
/* 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. */
for(i = 1; i <= N; i++)
{
   XXX_DisplayElt(i);
}

me semble déjà plus pertinent.

[gl]

cela montre surtout que le code explicite nécessite moins de commentaires à vue de pif biensûr...

Oui, c'est une évidence. Et heureusement qu'il en est ainsi.

[gl]

La génération du code ne se faisant pas a la volée, l'algorythme et les cheminements intellectuels qui ont précédé sa conception sont "le commentaire"

Si je comprends tes propos (je ne suis pas certain d'interpréter correctement la notion de cheminements intellectuels dans le cas présent), non ça devrait être dans les documents d'analyse, de conception ou de spécifications techniques.

Si vous pratiquez la méthode
variable a1 = h567=
fonction 645.12
procédure a578
Je vous souhaite bien du plaisir pour y revenir dès la semaine suivant l'écriture.

Il ne me semble pas avoir vu quelqu'un ici préconiser cette méthode (d'ailleurs même en dehors de cette discussion, je ne me souviens pas avoir rencontre quelqu'un soutenant sérieusement cette méthode).

[Antoine_935]

Le code du CERN le plus vieux est < 10 ans, en moyenne c'est quoi 5 ans ?

Le commentaire de la première révision indique
New repository initialized by cvs2svn.
Ca veut donc bien dire qu'ils avaient du code avant.

http://root.cern.ch/viewcvs/?pathrev=1

[hegros]

Ah! les OS ont les plus grands cycles de vie ! Peux-tu détaillé ton propos à ce sujet ?

Oui, plus ou moins, parce que lorsqu'on parle de code java ou c++ cela sous-entends 'en général' que c'est exécuté sous un système d'exploitation x soit la durée de vie des programmes des OS est forcément plus grande que la vie des programmes qui ont besoin d'un os pour s'executer.

Quid des programmes qui tourne sur du matériel sans os ? Par rapport à l'embarquer l'expérience est différente je ne le nie pas bien qu'il faut de toute façon un os pour compiler le programme.

C'est très empirique en même temps...

P.S.: au passage as-tu des statistiques fiables sur la durée de vie des différents types de logiciel ? Je n'ai jamais rien trouvé de probant à ce sujet.

non, aucune statistique fiable sur le sujet, mais vu le nombre réduit de programme système d'exploitation (Pos)écrit par rapport au nombre élevéde programme écrit nécessitant un système d'exploitation (Pprod). La dépendance de l'un à l'autre fait que la durée de vie > pour l'un que l'autre (hors programme ne nécessitant pas l'assistance de l'os, ce qui en fait un paquet aussi surement...)

Par contre un commentaire du style des deux-trois exemple fournis ou de celui-ci

Code :

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

1
2
3
4
5
6
/* 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. */
for(i = 1; i <= N; i++)
{
   XXX_DisplayElt(i);
}

me semble déjà plus pertinent.

Objectivement...non...c'est un code pour une partie générique de l'application parce que le DisplayElt n'est pas vraiment explicite...en plus je ne comprends pas l'interet...c'est pour le développeur avant qu'il implémente parce qu'après il faut vraiment avoir une bonne raison de modifier une telle partie de code (en maintenance par exemple)


D'après ces lectures et certains l'ont exprimé, les commentaires sont une sorte de technique de conception (ils devraient être écrit avant le code source) c'est presque un anti-pattern avec le DDT qui est aussi une technique de conception mais ne connaissant pas plus sur le sujet (qui bouge très vite) je ne saurais m'avancer sur une telle conclusion...

[gl]

Oui, plus ou moins, parce que lorsqu'on parle de code java ou c++ cela sous-entends 'en général' que c'est exécuté sous un système d'exploitation x soit la durée de vie des programmes des OS est forcément plus grande que la vie des programmes qui ont besoin d'un os pour s'executer.

Si ce n'est qu'un code peut tourner sous différents OS. Pour reprendre l'exemple de l'entreprise dans laquelle je suis actuellement, le code en question tourne sous différentes version de Windows (2000, XP, XP embedded, CE, NT4, 98, probablement Vista), sous différentes version de Linux, sous DOS (le vrai, pas la console Windows), d'OS maison à base de PSOS, VXWorks ou autre, etc.

A moins que tu ne considères que ce sont des logiciels différents. D'ailleurs quand tu parles de la durée de vie d'un logiciel peux-tu préciser ? En particulier la version 1.0.0 et la version 8.2.78 d'un même programme sont-ils dans le contexte de ton assertion un même logiciel ou deux logiciels distincts ?

Dans le deuxième cas de figure, je comprends mieux ta remarque quant à la faible durée de vie des logiciels (ceci étant, vu le rythme de sortie des noyaux Linux et des versions de Windows, les OS sont tout autant touchés que les autres logiciels).
Dans tous les cas, il n'empêche que la durée de vie d'une portion du code est potentiellement plus grande que celle du logiciel.

Objectivement...non...c'est un code pour une partie générique de l'application parce que le DisplayElt n'est pas vraiment explicite...en plus je ne comprends pas l'interet...c'est pour le développeur avant qu'il implémente parce qu'après il faut vraiment avoir une bonne raison de modifier une telle partie de code (en maintenance par exemple)

Oui, le nom est mal choisi, oui l'intérêt de décaler la numérotation des indices n'est pas flagrant (j'ignore même s'il y a un réel intérêt).
Non, ce n'est pas pour le développeur avant qu'il n'implémente.

Il s'agit d'un code qui utilise une bibliothèque externe ayant fait ces choix (peut être contestables, mais c'est un autre débat) et que l'on ne peut pas modifier. Il est donc exclus de changer le nom et de changer les indices. Le code ici est un simple utilisateur de la bibliothèque XXX et donc de la fonction XXX_DisplayElt().
La seule raison d'être de ce commentaire et de prévenir un futur mainteneur ou relecteur que la boucle [1..n] n'est pas une erreur.

Pourquoi ? Tout simplement parce que le jour où quelqu'un va mettre son nez dans ce code là (que ce soit pour une correction, une évolution ou autre), cette boucle va forcément le faire réagir et les grosso-modo, les réactions possibles sont :

• Il "corrige" cette boucle, ce qui va introduire une régression. Certes cette régression va être vu lors des tests et sera corrigé, mais on aura passer une itération de build/test pour rien avec la perte de temps que cela implique. C'est probablement la pire attitude possible.
• Il sort toute la documentation du projet et cherches la raison de ce choix. La encore ça peut être long, voire très long.
• Il sort la documentation de la bibliothèque externe. Encore faut-il qu'elle soit disponible et correcte (il existe des moyens de le garantir pour un code interne, pour un code externe c'est beaucoup plus compliqué) et là encore ça prends du temps.

Au final ce simple petit commentaire va permettre de gagner ce temps là. C'est tout, mais c'est déjà pas mal.

D'après ces lectures et certains l'ont exprimé, les commentaires sont une sorte de technique de conception (ils devraient être écrit avant le code source)

Utiliser les commentaires comme méthode de conception, est un point de vue que je ne partage pas et qui me semble pas très pertinent (mis à part dans le cas d'un code one-shot jetable).

Par contre il est tout à fait envisageable d'écrire les commentaires avant le code (mais après la conception) non pas en substitut de la conception mais en aide au développement (pense-bête pour le développeur), un peu comme on commence à écrire les prototypes de fonction et autres squelettes de classes avant l'implémentation. Ce style de commentaires disparaît généralement en partie au fur et à mesure de l'avancement du développement.

[Antoine_935]

c'est presque un anti-pattern avec le DDT

hérésie Cet avis n'engage que moi et est strictement personnel bien sur Le DDT deviendra bientôt une religion ^^

[gl]

En ce qui concerne la pratique SMSienne des programmeurs, je ne renvoie qu'au post précédent.

Que j'écrirai:
/Attention la bibliothèque XXX indice ces éléments de 1 à tous_sans_comments*/

For( sans_commentaires=1; sans_commentaires<= tous_sans_commentaires; sans_commentaires++)
{
writeln ("ils commentent beaucoup sur le forum la non nécessité de commenter");
}
C'est un exemple typique il y aura 2000 i dans un source.
Bien sur en variable locale...

Si ce n'est que dans les langages de type C, i, et dans une moindre mesure j, est un nom idiomatique pour un compteur de boucle n'ayant pas de sémantique particulière.
Ce n'est donc pas réellement un notation cryptique. Si cette indice à en outre une sémantique qui lui est associé, il est par contre préférable d'utiliser un nom en rapport avec cette sémantique.

Après les autres langages ont leur propre usage.

[Emmanuel Lecoester]

J'ai voté oui dans bien souvent des cas c'est ce qui reste après plus de 5 ans de bons et loyaux services : les spec générales n'ont pas été mises à jour et les spec détaillées n'ont pas suivies les évolutions.

Néanmoins je suis contre les commentaire qui commente le versionning ("-- correction fiche 200405". Le programme a été modifié depuis et en 2009 je me fous royalement des corrections de 2004. Dans le même registre je suis contre les commentaires du genre "-- définition des variables", "-- début du programme".

[hegros]

Tout d'abord pour reprendre le code de gl et situer le contexte, c'est une utilisation d'une fonction (XXX_DisplayElt) d'une bibliothéque que tu ne peux pas modifier.
Partons du principe que seul le code hors la fonction en elle-même est refactorable.

code de départ

Code :

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

1
2
3
4
5
6
7
/* 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. */
for(i = 1; i <= N; i++)
{
   XXX_DisplayElt(i);
}

code refactoré

Code :

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

1
2
3
4
5
6
7
/* 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. */
for(i = START_INDEX_CONVENTION; i <= N; i++)
{
   XXX_DisplayElt(i);
}

Autant i est très connu mais cela n'est à mon sens pas une justification, on gagnerait plus en lisibilité à écrire

code refactoré avec i inclus

Code :

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

1
2
3
4
5
6
7
/* 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. */
for(indexEltToDisplay = START_INDEX_CONVENTION; indexEltToDisplay <= N; indexEltToDisplay++)
{
   XXX_DisplayElt(indexEltToDisplay);
}

C'est un peu tiré par les cheveux et verbeux parce que je ne sais pas exactement dans quel module nous sommes précisément, mais cela est plus 'lisible'. Est-ce que le commentaire apporte encore une plus-value ? ...

Sinon est-ce que cela voudrait dire que partout dans le code où on utilise cette bibliothéque alors on va dupliquer ce commentaire pour rappeler que l'indice commence à 1 et non 0 ?

A moins que tu ne considères que ce sont des logiciels différents. D'ailleurs quand tu parles de la durée de vie d'un logiciel peux-tu préciser ? En particulier la version 1.0.0 et la version 8.2.78 d'un même programme sont-ils dans le contexte de ton assertion un même logiciel ou deux logiciels distincts ?

Début de vie : lancement du projet, première phase de développement
Fin de vie : le logiciel n'est plus maintenue ou supprimé/remplacé par un autre logiciel (comprenez on a décidé de le remplacer complètement)

C'est le même logiciel pour ton exemple à moins qu'entre la 1.0.0 et la 8.2.78 vous ayez réécris complétement TOUT le code et qu'il porte un autre nom

Oui, le nom est mal choisi, oui l'intérêt de décaler la numérotation des indices n'est pas flagrant (j'ignore même s'il y a un réel intérêt).
Non, ce n'est pas pour le développeur avant qu'il n'implémente.

Merci de le préciser que ce n'est pas pour avant l'implémentation parce qu'effectivement il y a eu un mélange avec la technique du documenter avant de coder qui ressemble plus à une technique de conception utilisé surtout dans les cycles en cascades V etc...

[Antoine_935]

Néanmoins je suis contre les commentaire qui commente le versionning ("-- correction fiche 200405". Le programme a été modifié depuis et en 2009 je me fous royalement des corrections de 2004.

Parles-tu des notes ajoutées au commit dans les SCM ? Dans ce cas je ne suis pas d'accord avec toi. Ces notes sont très utilses pour savoir ce qui a été fait et pouvoir plus tard sortir un changelog.

Pour le reste, entièrement d'accord


@hegros: je trouve qu'utiliser des noms aussi longs que indexEltToDisplay rend non seulement la lecture plus difficile, mais en plus l'écriture plus rébarbative, même avec l'autocomplétion. C'est plus simple de spécifier en commentaire au dessus de la boucle à quoi correspond i, s'il est besoin de le préciser...

[hegros]

@hegros: je trouve qu'utiliser des noms aussi longs que indexEltToDisplay rend non seulement la lecture plus difficile, mais en plus l'écriture plus rébarbative, même avec l'autocomplétion. C'est plus simple de spécifier en commentaire au dessus de la boucle à quoi correspond i, s'il est besoin de le préciser...

C'est subjectif il y a tellement de profil de lecteur de code différent (sans compter les machines automatiques). Une ligne de programme peut aller jusqu'à combien 100 caractères autant utiliser l'espace blanc et combler avec de la sémantique et de l'expressivité

[gl]

Mais i ou j c'est pareil. Même dans un boucle de comptage, il faut expliciter les variables. On sait au moins ce qu'on compte.
Ne pas oublier qu'on doit se maintenir le code parfois 10 ans plus tard.

Je ne disais pas le contraire (ou alors je m'exprime mal). Lorsque le compteur a un sens, oui il faut lui donner un nom exprimant ce sens (c'est ni plus ni moins ce que je disais tout à l'heure).

Maintenant lorsqu'il s'agit d'un compteur purement technique, il est difficile de donner un nom explicite : index, indice, ElementNumber ou tout autre appellation du même style n'apporte aucune précision particulière et je ne vois pas de plus value (ni en lisibilité, ni en quoique soit d'autre) par rapport à un index nommé i (avec les précautions habituelles bien entendu) tant le nom i est devenu le nom consacré.

Paradoxalement, l'utilisation i est devenu tellement classique que pour un développeur lambda la compréhension de la forme for(i=0, ...) est souvent plus immédiate qu'une forme avec un nom plus parlant [1]. Maintenant, doit-on s'en réjouir ou le regretter, c'est une autre question.



[1] Il s'agit là d'un simple constat lié à ce que je vois tout les jours, pas une vérité absolue, il est probable que le constat soit différent ailleurs.
Pour la petite histoire, lorsque j'ai commencé à travaillé, j'essayais de trouver des noms plus parlant que i pour les simples compteurs de boucles, jusqu'à ce que je me rende compte que les différents lecteurs (moi compris) devaient prêtaient plus d'attention pour comprendre cette boucle que lorsque i était utilisait comme indice.

[Antoine_935]

C'est subjectif il y a tellement de profil de lecteur de code différent (sans compter les machines automatiques). Une ligne de programme peut aller jusqu'à combien 100 caractères autant utiliser l'espace blanc et combler avec de la sémantique et de l'expressivité

80 caractères, pour C et Python du moins. Il en va peut-être autrement pour d'autres langages, mais je ne connais pas les détails.

Cela dit, on n'est pas obligés de remplir tout, et les espaces blancs aident souvent à la lecture

[millie]

Néanmoins je suis contre les commentaire qui commente le versionning ("-- correction fiche 200405".

Alors, il y a un cas où je ne sais pas si tu considère ça comme du versionning.

J'avais bossé sur un projet pour un client. On lui livrait les sources et il faisait ce qu'il voulait avec. Quand il voulait des "grosses" modifications fonctionnels, il utilisait le "support" sur l'application pour demander des modifications. Le client renvoyait son source qui avait pu être modifié par lui.

S'en suit une analyse fonctionnelle et une analyse technique où les modifications à apporter sont décrites (notamment, les fichiers qui vont être modifiés etc.).
A chaque intervention dans un fichier, j'ajoutais au bon endroit quelque chose du type : @entreprise:date Pourquoi de la modif.
Cela permettait quand il récupérait ses sources au final de voir immédiatement dans le source les modifications apportaient par nous (pour pas qu'il supprime "bêtement" vu que ce code ne lui dit rien). La date est plus informative qu'autres choses pour le client.

Il n'était pas trop possible ici d'avoir un gestionnaire de source commun entre le client et nous.

[gl]

Tout d'abord pour reprendre le code de gl et situer le contexte, c'est une utilisation d'une fonction (XXX_DisplayElt) d'une bibliothéque que tu ne peux pas modifier.
Partons du principe que seul le code hors la fonction en elle-même est refactorable.

code de départ

Code :

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

1
2
3
4
5
6
7
/* 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. */
for(i = 1; i <= N; i++)
{
   XXX_DisplayElt(i);
}

code refactoré

Code :

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

1
2
3
4
5
6
7
/* 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. */
for(i = START_INDEX_CONVENTION; i <= N; i++)
{
   XXX_DisplayElt(i);
}

Autant i est très connu mais cela n'est à mon sens pas une justification, on gagnerait plus en lisibilité à écrire

code refactoré avec i inclus

Code :

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

1
2
3
4
5
6
7
/* 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. */
for(indexEltToDisplay = START_INDEX_CONVENTION; indexEltToDisplay <= N; indexEltToDisplay++)
{
   XXX_DisplayElt(indexEltToDisplay);
}

C'est un peu tiré par les cheveux et verbeux parce que je ne sais pas exactement dans quel module nous sommes précisément, mais cela est plus 'lisible'. Est-ce que le commentaire apporte encore une plus-value ? ...

Comme expliqué dans mon message précédent à Chicanau, utilisé un nom d'indice purement technique autre que i apporte, de ce que j'ai pu constaté, plus de confusion qu'autre chose.

L'utilisation d'une borne de départ nommé permet effectivement d'attirer l'attention sur le fait qu'il y a quelque chose de pas classique. Pour aller au bout de l'idée, il faudrait d'ailleurs remplacer <= N par < STOP_INDEX_CONVENTION avec STOP_INDEX_CONVENTION = N+1.

Maintenant est-ce que cela se substitue au commentaire ? Je ne pense pas. En effet, la construction n'est plus tout académique et on devrait bien comprendre qu'il ne s'agit pas d'une erreur mais d'un choix délibéré, ce qui est une partie de l'objectif recherché. Mais on ne sait toujours pas pourquoi, ce qui était le deuxième objectif du commentaire.

On pourrait imaginer d'utiliser des noms plus long pour les bornes et l'indice qui intégrerait cette notion, mais au final on aurait probablement des identifieurs à rallonge qui posent autant de problèmes qu'ils n'en résolvent. Les noms à rallonge et les lignes trop longue pour rentrer sur un écran ne sont en effet pas très agréable à lire (à titre personnel, je préfère lire une ou deux lignes de commentaires en bon français ou en bon anglais qu'une suite de 50 caractères contigus représentant 5 ou 6 mots accolés entre eux sans respect de la moindre grammaire, mais je te l'accorde c'est là avant tout une question de goût).

Sinon est-ce que cela voudrait dire que partout dans le code où on utilise cette bibliothéque alors on va dupliquer ce commentaire pour rappeler que l'indice commence à 1 et non 0 ?

probablement pas.

Dans le cas auquel je me réfère [1], la construction n'apparaissait qu'une fois.

Sinon non, dupliquer ce commentaire n'est certainement pas une bonne chose. Tout comme ce n'est pas une bonne chose de dupliquer cette construction "originale".
J'aurais plutôt tendance à encapsuler cette bibliothèque dans un code s'utilisant de manière classique et gérant ce décalage d'indice. Ainsi le code incriminé et le commentaire lié sont localisés à un endroit clairement défini.

Début de vie : lancement du projet, première phase de développement
Fin de vie : le logiciel n'est plus maintenue ou supprimé/remplacé par un autre logiciel (comprenez on a décidé de le remplacer complètement)

C'est le même logiciel pour ton exemple à moins qu'entre la 1.0.0 et la 8.2.78 vous ayez réécris complétement TOUT le code et qu'il porte un autre nom.

OK, on a donc la même référence. Partant de cette référence, voici quelque logiciel qui ont une bonne vingtaine d'année :

• gcc dont la version 1.0 date de 87
• vi dont la version originale date de la fin des années 70. Vim date pour sa part du début des années 90.
• La première version d'Emacs date des années 80.

Certes, ces programmes ont fortement évolué durant toutes ces années et il y a fort à parier qu'une grande partie du code source a été réécrit depuis l'origine.
Mais je ne parierait pas qu'on ne trouve plus du tout du code des origines dedans. Ceci dit n'ayant pas particulièrement envie de me palucher tout le code source, je n'irais pas le vérifier.

Sinon, professionnellement parlant comme je l'ai déjà exposé, il m'arrive parfois de travailler sur des projets qui ont 10 ou 20 ans et de trouver dedans du code d'origine. Sans parler de code plus ancien ayant été réutilisé.



[1] Oui, car cette construction alambiqué est fortement inspiré d'un cas réel sur lequel j'étais tombé (en tant que mainteneur du code, je ne l'avais pas commis) où il n'y avait pas de commentaire. Je ne t'explique pas combien de temps j'ai mis à comprendre pourquoi il y avait ce code bancal (il faut dire que le projet en question ne brillait pas non plus par la qualité de la documentation, au contraire).