Discussion :

[Rayek]

Il faut bien comprendre qu'il y aura toujours quelqu'un qui ne comprendra pas. Mais est-ce qu'on doit en tenir compte si c'est quelqu'un qui ne connait pas le langage ? Est-ce qu'on doit en tenir compte si c'est quelqu'un qui y a à peine touché ? Ces personnes là ne sont pas censées toucher au code, donc on n'a pas à les prendre en compte. On ne met pas quelqu'un sur un travail où il n'a pas les capacités même les plus basiques. C'est là qu'il faut faire la différence entre commentaire et tutoriel. De même entre commentaire et documentation. On informe sur des niveaux différents :
- la documentation décrit une boite noire (e.g. entrée, sorties et éventuellement dommages collatéraux), peu importe que ce soit pour ceux qui savent coder ou non
- un tutoriel forme ceux qui ne savent pas coder initialement pour qu'ils sachent coder après
- les commentaires décrivent des lignes de codes spécifiques, là où le programmeur va mettre les mains dans le cambouis, et donc celui qui sait programmer va devoir comprendre les particularités du bout de code spécifique

Un tutoriel peut utiliser des codes commentés et documentés, mais un commentaire ou de la documentation n'a pas pour vocation première à former quelqu'un au langage.

Tant qu'on ne fera pas cette distinction, on pourra dire tout ce qu'on veut de "il faut commenter chaque ligne" à "les commentaires c'est le mal". Tant qu'on ne définit pas correctement le contexte, on peut prôner tout et n'importe quoi. Pour moi la majorité c'est commenter pour les développeurs qui devront reprendre le code pour l'améliorer (et non pour ceux qui se formeront au langage) et dans ce contexte il est important de coder proprement et de ne pas surcharger de commentaires.

Il y a aussi des standards de codage (conventions de nommage, algorithmes connus, etc.) qui permettent d'avoir un socle commun, donc l'argument "ce que toi tu écris, moi je peux ne pas le comprendre", ça tient pour ceux qui ne parlent pas la même langue : si l'un utilise des standards et l'autre fais tout à sa sauce... ben écoute, le deuxième aura toujours le même problème, le premier n'aura de problème qu'avec le second. Après c'est un choix, on suit la masse ou pas. Si tu apprends le français, c'est pour pouvoir parler en français avec des francophones, ou c'est pour parler un patois ? Si c'est le second cas, ben assume, faut pas sans arrêt mettre la faute sur les autres sous prétexte qu'on a le droit de faire les choses différemment. Il faut toujours un socle commun pour se mettre d'accord, si on n'a pas ce socle, on ne peut pas tomber d'accord. Le tout étant après de savoir ce qu'on y met dans ce socle.

Je le répète, je n'ai jamais dit qu'il fallait commenter chaque ligne du code. Mais dans le cas où dans une équipe tu as plusieurs développeurs et que tous n'ont pas le même niveau, tu fais quoi ?
Tu te limites en codage parce que les autres ne cherche pas à évoluer ?
Ou bien tu fais quand même mais tu commentes les passages un peu complexe ?

J'ai le problème dans l'équipe dans laquelle je suis. Je suis le seul à chercher des nouveautés sur le langage et les évolutions. donc pour pas qu'ils se "perdent dans le code", je commentes un peu plus que la normale.

[Matthieu Vergne]

Mon post précédent visait seulement à mettre en garde sur la prise en compte du contexte : il ne s'agit pas de dire que "quelqu'un" peut ne pas comprendre pour justifier une ligne de commentaire. Ce quelqu'un doit avoir un minimum d'intérêt à mettre les mains dans le code, il ne s'agit pas de prendre une personne au pif dans la rue et de lui demander ce qu'elle en pense. Et ceux qui disent "tu ne sais jamais qui passera derrière toi" ou "tout le monde n'a pas le même niveau" se contentent de sortir des évidences générales, qui ne tiennent compte d'aucun contexte. Du coup on ne peut pas leur donner tord (dans le fond, c'est vrai), mais on peut imaginer tout et n'importe quoi. Tu ne sais peut-être pas qui passera derrière toi, mais tu sais au moins que ce ne sera pas un bleu complet, parce qu'il aura été embauché pour ça.

Et ceux qui répondront "ben si, ça peut être un bleu", je répondrai que vos commentaires ne changeront pas grand chose, parce que le bleu ne saura de toute façon pas quoi faire de vos commentaires (à supposer qu'il les lise ET qu'il les comprenne).

[g.Arnaud]

Quand on travaille dans une boite et/ou avec une équipe, il y a des conventions. Celle ci peut-être définit dans de la doc, il y a aussi des outils pour Visual Studio pour vérifier que ces conventions sont bien respecté.

Il y a aussi à avoir une certaines cohérence quand on code. On ne va pas choisir le même nom de variable pour représenter 2 choses différentes. On ne va pas non plus choisir un nom différent pour représenter la même chose dans des fonctions différentes.

Dans ce projet, ctx a été choisit pour représenter le contexte EF et c'était utiliser tout le long du projet. De plus le choix du nom "personne" au lieu de "p" aurait pu être pertinent s'il apportait une réelle information supplémentaire (travaillant sur une collection de "Personne", "p" ne peut-être qu'un objet "Personne"). Ici le choix d'un nom de variable très court permet de voir tout de suite l'essentiel du code.

Et ensuite, un code doit être documenté par la documentation dans le code et par des documents complémentaires expliquant l'architecture de l'application et aussi les conventions de nommage.

(d'ailleurs visual studio permet de considérer l'absence de documentation d'une fonction comme étant une erreur et ne compilera pas)

Ce que Rayek indique qu'il manque généralement aux questions sur le forum doit être présent dans la documentation et non dans les commentaires. Si tu fais une migration d'une version de delphi à une autre, tout les commentaires serait à corriger et si ça n'ai pas fait, induirait en erreur.

Ensuite, on ne peut pas commenter l'intégralité du code comme s'il était destiné à de parfaits débutants. Celui qui reprends le code doit avoir un certain niveau après, il faut savoir ou placer cette barre de niveau.

Les commentaires ne sont pas là pour donner des cours de développement à ceux qui les lisent.

Après, je suis d'accord que si tu met des nouveautés ou du code inhabituel qui n'est pas compréhensible à la première lecture, il doit être commenté.
Si un nouveau composant, une nouvelle librairie est utilisé et ce à un seul endroit du code, un commentaire contenant un liens vers la doc est la bienvenue.

Après, une bonne démarche qualité dans le code rends bon nombre de commentaire inutile. Et après les commentaires doivent être présent seulement quand il n'est pas possible d'expliquer autrement. Et il est préférable dans ces commentaires d'avoir le "pourquoi" que le "comment".


Il y a une seule chose selon moi qui doit être commenter à chaque fois, c'est les optimisations (ne pas oublier de garder la version propre en documentation).

[chaying]

En tout cas, apres 11 pages de commentaires sur le fait de savoir s'il faut ou non des commentaires, je suis sur d'une chose : trop de commentaires tue le commentaire !

[Matthieu Vergne]

Comme tout le reste {^_^}.

[ngthurel]

Il est clair qu'un code bien écrit a besoin de commentaires car il faut toujours prévoir les évolutions du programme qui le contient ainsi que les éventuelles maintenances.

[sekaijin]

perso je pense qu'il faut toujours commenté
mais le pb c'est de ne pas "copier coller le code"

par example

Code :

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

productDataSource connect withUser aUser andPassword aPass;

je trouve débile de commenter une telle ligne avec se connecter à la base des produit avec le login aUser et le password aPass.
c'est mal heureusement ce que je trouve souvent.

dans le même ordre d'idée je pense qu'il vaut mieux bien nommer ses paramètre que de mettre trois tonnes de commentaires
exemple récent en javasend(String arg0, String arg1, String arg2, String arg3)avec comme commentaire send arg0 object to partner whith arg1, arg2, arg3 parameters".

enfin je pense aussi que mieux vaut un algo clair et verbeux (plus de lignes à écrire) qu'une optimisation obscure. le commentaire pourra toujours tenter d'expliquer ce que ça fait. si 20 ou 30 ans après lorsque une persone devra reprendre la chose s'il ne comprends pas l'algo il ne pourra pas intervenir. (nous vivons tous les jours ce genre de situation avec des veux cobol et autres fortran) votre code d'aujourd'hui sera peut-être dans la même situation demain.

le métier de développeur à quelque chose de contradictoire. c'est un boulot dans le quel une grande part du travail est un travail personnel. même si on bosse en équipe, on ecrit soit même son code, on le conçois, on le teste. on réfléchit souvent soit même au besoin (on l'interprète). bref c'est un travail centré sur le développeur lui même. nous mettons beaucoup de nous dans notre code. Mais ce que nous produisons est destiné à être utilisé par d'autre qui n'ont absolument pas le même mode de pensés. notre code sera réutilisé, maintenu, modifié, réécrit par d'autre développeurs. en clair lorsque nous produisons du code il vient pour une grande par de nous même. Mais il sera toujours ou presque pris en main par quelqu'un dautre.

j'utilise beaucoup dans mon équipe le principe du candide. je demande à quelqu'un d'externe au projet de relire le code et de me dire ce qu'il ne comprends pas. lorsque nous produison une API quelqu'elle soit je demande à quelqu'un qui ne connait rien au dommaine si avec la doc il se sens capable de la mettre en oeuvre. et tout cela ce trouve dans la docummentation du code.

A+JYT

[Matthieu Vergne]

+1 pour la relecture par un tiers. C'est d'ailleurs un des principes agiles (faire tourner les gens sur le code) et notamment XP (programmer par binômes).

[koala01]

Salut,

J'avouerai ne pas avoir lu les 200 et quelques interventions, et n'avoir même pas lu l'article en lui-même

Personnellement, je pense qu'il faut distinguer deux sortes de commentaires:

Les commentaires de "documentation" d'une part et les commentaire "d'implémentation" d'autre part.

Pour les premiers, je parle du "cartouche" qui explique le but et la raison d'être d'une classe ou d'une fonction.

J'estime que ce cartouche devrait être systématique et "aussi complet que possible", en indiquant:

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

Outre le fait de permettre la génération automatique de documentation, ce genre de commentaire a généralement l'énorme avantage d'être particulièrement stable dans le temps:

Qu'il s'agisse d'un "comportement exclusivement interne" ou d'un service accessible "par n'importe qui", la seule chose qui mériterait que l'on revienne dessus serait un changement au niveau des spécifications, et encore!

D'aucuns me diront que cela fait double emploi avec les specs oui, et alors

Les spécifications indiquent ce que l'on veut, ce cartouche indique comment l'utiliser pour obtenir ce que l'on veut

Ensuite, on peut parler de ce que j'ai nommé les "commentaires d'implémentation".

Ce sont ces commentaires qui se trouvent directement dans l'implémentation d'une fonction.

A leur sujet, je tend plutôt vers la solution inverse: il ne devrait pas être nécessaire de rajouter un commentaire dans le code.

Parmi les interventions que j'ai lues (oui, j'en ai quand même lu quelques unes ), beaucoup de gens parlaient "d'algorithmes particulièrement complexes".

De mon avis sur la question, il n'existe aucun algorithme, aussi complexe pusse-t-il être, qui ne puisse "assez facilement" être subdivisé en différentes étapes, quitte à créer, pourquoi pas, une structure (ou une classe ou un helper) qui prenne l'une ou l'autre de ces étapes en charge.

Il ne faut, bien sur, pas entrer dans l'exces en ce qui concerne les noms de variables et en arriver à des variable qui imposent un défilement horizontal sur 120 caractères rien que pour être en mesure de lire le nom de la variable (ou de la fonction), mais si l'on respecte déjà un tant soit peux deux des règles "classiques" que sont la loi de déméter et le principe de la responsabilité unique, il devient tout à fait possible d'avoir des noms à la fois simples et clairement explicites!

Je lisais qu'un intervenant commençait par écrire en commentaire les différentes étapes de son algorithme.

La question qui m'est directement venue à l'esprit a été "mais pourquoi ne crée-t-il pas une fonction différente pour chacune d'elles ".

En effet, s'il existe une fonction qui correspond à chaque étape de l'algorithme, non seulement l'algorithme complet peut se "contenter" d'être l'appel à chacune de ces fonctions, mais, en plus, cela permet de les réutiliser "par ailleurs" en cas de besoin.

Cela ne présente que des avantages, car il est possible de tester les différentes parties de manière indépendantes, et cela nous permet en outre d'éviter d'avoir à répéter du code si, d'aventure, nous avons besoin d'une de ces parties spécifique.

Évidemment, il s'agira de trouver le nom explicite adéquat pour chacune de ces fonctions

[Paul TOTH]

...

je suis d'accord avec ton idée de cartouche, par contre l'implémentation nécessite aussi des commentaires.

évidemment on ne commente pas tout, une fonction de 2 lignes avec un commentaire sur 4 lignes ça semble exagéré...encore que

Code :

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

1
2
#define somme()

mais pourquoi donc voudrait-on que la fonction somme ne serve à rien ? quelques lignes de commentaires peuvent s'avérer nécessaires alors que le "code" se limite à un grand vide.

d'autre part, vous qui pensez que le code est si limpide qu'un commentaire ne pourrait en être qu'un plagiat verbeux, je vous admire. Vous êtes capables d'écrire un code dans du marbre, il est tellement beau qu'on pourrait l'encadrer ! jamais il ne subira de modification car il est parfait dès sa rédaction.

moi je suis moins doué que ça, mon code, parfois vieux de plusieurs années nécessite des ajustements, soit parce qu’il était erroné, soit parce que son usage a évolué. Mon code est vivant (n'est pas mort qui à jamais dort), et les raisons de son évolution sont souvent l'objet de commentaires. Si la modification est venue après coup, c'est que sa nécessité n'était justement pas une évidence et le commentaire prend tout son sens.

L'absence de commentaires c'est un peu pour moi comme faire des mathématiques en toutes lettres, ou remplacer le menu du restaurant par un livre de cuisine. Ce midi je prendrais bien

- 800 g de boeuf 
- 100 g de lardons
- 50 g de beurre ou 3 cuillères à soupe d'huile
- 2/3 de litre de vin rouge
- 2 oignons
- ail
- 2 cuillères à soupe de farine
- 1 bouquet garni
- sel, poivre
- 250 g de champignons de Paris

bien cuit.

[koala01]

d'autre part, vous qui pensez que le code est si limpide qu'un commentaire ne pourrait en être qu'un plagiat verbeux, je vous admire. Vous êtes capables d'écrire un code dans du marbre, il est tellement beau qu'on pourrait l'encadrer ! jamais il ne subira de modification car il est parfait dès sa rédaction.

Je ne dis pas qu'il l'est d'office, je dis qu'il devrait l'être.

Mais ce qu'il faut surtout, c'est faire la part entre les modifications dues aux adaptations des besoins et ceux dus à la correction de bugs.

Un code correct ne devrait pas être modifié suite à une évolution des besoins (respecter l'OCP (Open Close Principle), ou si tu préfères le principe ouvert (à l'évolution) /fermé (à la modification)), et c'est là que se trouve tout l'intérêt de respecter le principe de la responsabilité unique: Tant que la fonction présente le comportement que l'on attend de sa part (et qu'il n'y a pas de bug), on peut décider de l'utiliser n'importe où, a priori, sans avoir à la modifier.

Maintenant, si tu dois corriger un bug, et que tu indiques le numéro d'issue dans le code afin de savoir quel bug ta modification résout, cela peut se comprendre

Mais si tu modifies ton code uniquement pour une question d'optimisation (est-elle nécessaire ), ton code devrait veiller à rester "suffisamment simple et explicite" pour que tout commentaire devienne inutile

moi je suis moins doué que ça, mon code, parfois vieux de plusieurs années nécessite des ajustements,

Encore une fois, s'il nécessite des ajustements, c'est sans doute que tu n'as pas "suffisamment" délégué les responsabilités.

A moins, bien sur, que les besoins aient évolué à un point tel qu'une partie de ton code soit purement et simplement dépréciée.

Mais, dans ce cas, ton code ne devrait pas être modifié, mais marqué pour "suppression programmée"

soit parce qu’il était erroné,

S'il est erroné, on entre dans la correction de bug.

Mais, à moins de placer simplement un numéro d'issue, s'il faut des commentaires suplémentaires, c'est que ton code est déjà trop compliqué en soit: KISS reste malgré tout le meilleur conseil de l'Xp

Mon code est vivant (n'est pas mort qui à jamais dort), et les raisons de son évolution sont souvent l'objet de commentaires.

Tout code est vivant, mais en respectant les principes solid et la loi de déméter, les modifications du code ne devraient pas justifier l'apparition de commentaires

Si la modification est venue après coup, c'est que sa nécessité n'était justement pas une évidence et le commentaire prend tout son sens.

C'est alors un défaut d'analyse fonctionnelle...

Dans le pire des cas, cela pourrait se traduire par une modification du cartouche (je ne parle que des commentaires, et pas de la modification du code en elle-même ), dans le meilleur des cas, cela devrait surtout se traduire par l'apparition (ou la disparition) de fonctions (de types ) spécifiques

[g.Arnaud]

Il manque pas les carottes à ton bœuf bourguignon?

Ce que tu nous donnes correspondrait plus aux variables d'une fonction, il manque les étapes de la recettes et le nom de la fonction.

Après quand je vois du code commenter de cette façon

Code :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
uint factoriel(uint i)
{
     //On initialise res à 1
     uint res = 1;
     //Pour j de 2 à i
     for(uint j = 2;j<i;j++)
     {
          //on multiplie res par j
          res *= j;
     }
     //on retourne res
     return res;
}

C'est le genre de commentaire qu'on retrouve surtout dans du code fait par des débutants.
Ces commentaires ne donnent aucunes informations utiles. Un développeur devrait comprendre ce code sans les commentaires.

Les commentaires doivent être là pour dire ce que le code ne dis pas.
Exemple pour de l'optimisation

Code :

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

1
2
3
4
//La multiplication par 8 se traduit par un décalage de bit à la compilation
//Un décalage de bit suivit d'une soustraction est plus performant
//qu'une multiplication par 7
int b = (a*8)-a;

[DevTroglodyte]

...

En gros, tu écris des programmes qui n'évolueront jamais, et qui ne seront retouchés (voire relus) par personne...

C'est bien joli le monde des bisounours, mais dans la vraie vie, c'est bien différent, hein. Il y aura forcément une personne qui va repasser à un moment sur ton code (maintenances, évolutions, ...), et avoir un code commenté prend alors toute son importance.

C'est bien joli de dire "un code bien clair et bien écrit n'a pas besoin de commentaires" (ouais c'est sur, je comprends mon code. Mon voisin, c'est moins sur. Et le type qui va le relire dans 5 ans parce que telle techno aura évolué et qu'il faudra faire une adaptation encore moins), mais c'est être très loin de la réalité, là.

[Paul TOTH]

Je ne dis pas qu'il l'est d'office, je dis qu'il devrait l'être.

ça se dit aussi "il y a la théorie... et la pratique"

Mais ce qu'il faut surtout, c'est faire la part entre les modifications dues aux adaptations des besoins et ceux dus à la correction de bugs.

...

A moins, bien sur, que les besoins aient évolué à un point tel qu'une partie de ton code soit purement et simplement dépréciée.

Mais, dans ce cas, ton code ne devrait pas être modifié, mais marqué pour "suppression programmée"

la belle affaire, donc le code qui produit un report HTML 4 doit juste être supprimé, car la fonction d'export HTML 5 sera un tout nouveau développement...d'ailleurs on envisage pas un instant qu'il soit possible de demander à ce code de fournir au choix du HTML 4 ou 5

S'il est erroné, on entre dans la correction de bug.

Mais, à moins de placer simplement un numéro d'issue, s'il faut des commentaires suplémentaires, c'est que ton code est déjà trop compliqué en soit: KISS reste malgré tout le meilleur conseil de l'Xp
Tout code est vivant, mais en respectant les principes solid et la loi de déméter, les modifications du code ne devraient pas justifier l'apparition de commentaires
C'est alors un défaut d'analyse fonctionnelle...

Dans le pire des cas, cela pourrait se traduire par une modification du cartouche (je ne parle que des commentaires, et pas de la modification du code en elle-même ), dans le meilleur des cas, cela devrait surtout se traduire par l'apparition (ou la disparition) de fonctions (de types ) spécifiques

ok, tu parts dans de l'abstraction, des interfaces, du polymorphisme ? c'est à mon avis l'endroit où les commentaires sont le plus utiles ! Quoi de moins explicite qu'une classe virtuelle - oui vas-tu me dire, c'est justement parce qu'elle est ouvert et qu'on peut l'utiliser comme on veux - non te répondrais-je car elle a été conçue dans un contexte particulier qui lui a donné vie et son niveau d'abstraction est complètement lié à ce contexte car l'anticipation a ses limites.

Combien de fois ai-je lu que telle classe ou telle interface est particulièrement mal conçue ! C'est peut-être vrai, mais c'est souvent liée à une méconnaissance du contexte dans lequel elle a été crée.

[Paul TOTH]

Il manque pas les carottes à ton bœuf bourguignon?

t'es aussi fort en programmation qu'en cuisine alors moi je sais pas c'est un copier/coller ^^

Ce que tu nous donnes correspondrait plus aux variables d'une fonction, il manque les étapes de la recettes et le nom de la fonction.

Après quand je vois du code commenter de cette façon...

je verrais plus un commentaire du genre

Code :

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

1
2
3
4
5
6
7
8
9
10
11
// fonction suffisante car nous ne dépasserons jamais 10! (cf CdC §5)
uint factoriel(uint i)
{
     uint res = 1;
     for(uint j = 2;j<i;j++)
     {
          res *= j;
     }
     return res;
}

[koala01]

En gros, tu écris des programmes qui n'évolueront jamais, et qui ne seront retouchés (voire relus) par personne...

Absolument pas!

C'est bien joli le monde des bisounours, mais dans la vraie vie, c'est bien différent, hein. Il y aura forcément une personne qui va repasser à un moment sur ton code (maintenances, évolutions, ...), et avoir un code commenté prend alors toute son importance.

Ce qui prend toute son importance, c'est que le code soit compréhensible.

Mais l'utilisation de commentaires est, non seulement, loin d'être la meilleure manière de rendre un code compréhensible, mais aussi, et surtout, la manière sans doute la plus dangereuse.

Les deux choses les plus efficaces pour rendre un code compréhensible sont des noms explicite et une bonne délégation des tâches (SRP inside : chaque classe, chaque fonction ne doit avoir qu'une seule responsabilité mais doit s'en occuper correctement)

Si je dis que les commentaires à l'intérieur du code sont la manière la plus dangereuse pour rendre un code compréhensible, c'est "uniquement" parce que celui qui modifiera le code peut "oublier" de modifier le commentaire en conséquence.

Il y a alors un écart entre ce que l'on lit que le code devrait faire et ce que le code fait réellement.

S'il faut aller effectuer une correction dans ce cas, on ne sauras plus s'il faut se baser sur le commentaire ou apporter une correction en respectant ce que le code fait réellement pour l'instant.

C'est bien joli de dire "un code bien clair et bien écrit n'a pas besoin de commentaires" (ouais c'est sur, je comprends mon code. Mon voisin, c'est moins sur. Et le type qui va le relire dans 5 ans parce que telle techno aura évolué et qu'il faudra faire une adaptation encore moins), mais c'est être très loin de la réalité, là.

Si tes noms sont explicites, le voisin ou type qui viendra dans vingt ans relire ton code saura comprendre ce que ton code effectue, meme si la technologie n'est plus utlisée ou a évolué

la belle affaire, donc le code qui produit un report HTML 4 doit juste être supprimé, car la fonction d'export HTML 5 sera un tout nouveau développement...d'ailleurs on envisage pas un instant qu'il soit possible de demander à ce code de fournir au choix du HTML 4 ou 5

Si tu me sors une fonction qui sort une page HTML (quelle qu'en soit la norme) allant des en-tête aux pied de page d'une seule traite, je te pend au premier arbre qui passe par là

Si ton code est correct, tu auras sans doute effectivement une fonction "d'entrée" qui fera appel à un ensemble d'autres fonctions plus spécifiques.

Il y a donc deux solutions:
Soit tu veux passer à un seul rapport qui suit la norme HTML5, et, dans le pire des cas, tu ne devra modifier que les fonctions pour lesquelles il y a une différence entre HTML4 et HTML5.
Soit tu veux pouvoir choisir la norme de sortie de ton rapport.

Dans ce cas, tu ne change aucune des fonctions existante, mais tu rajoutes des fonctions (ou tu en redéfini le comportement dans une classe dérivée, selon le cas) pour les partie qui utilises la norme HTML5.

Le choix entre la fonction qui fournit un code suivant la norme HTML5 se fera donc soit par polymorphisme, soit sur base d'une variable qu'il t'appartiendra de nommer correctement.

Si le nom de ta variable dit explicitement qu'elle sert au choix de la norme envisagée, une condition dans le code qui appelle les différentes fonctions sera tout aussi lisible et compréhensible qu'un commentaire

ok, tu parts dans de l'abstraction, des interfaces, du polymorphisme ? c'est à mon avis l'endroit où les commentaires sont le plus utiles ! Quoi de moins explicite qu'une classe virtuelle - oui vas-tu me dire, c'est justement parce qu'elle est ouvert et qu'on peut l'utiliser comme on veux - non te répondrais-je car elle a été conçue dans un contexte particulier qui lui a donné vie et son niveau d'abstraction est complètement lié à ce contexte car l'anticipation a ses limites.

C'est justement pour cela que l'héritage et le polymorphisme existent: pour te permettre d'adapter un comportement particulier à un type d'objets particulier sans avoir à modifier les comportements existants (tout en restant libre, le cas échéant, de les réutiliser)

Combien de fois ai-je lu que telle classe ou telle interface est particulièrement mal conçue ! C'est peut-être vrai, mais c'est souvent liée à une méconnaissance du contexte dans lequel elle a été crée.

Les classes mal conçues sont beaucoup plus souvent dues au non respect (ou à une mauvaise compréhension / mise en oeuvre) des principes SOLID dont je parlais la tantot, LSP et SRP en tête

[pseudocode]

De mon avis sur la question, il n'existe aucun algorithme, aussi complexe pusse-t-il être, qui ne puisse "assez facilement" être subdivisé en différentes étapes, quitte à créer, pourquoi pas, une structure (ou une classe ou un helper) qui prenne l'une ou l'autre de ces étapes en charge.

De mon expérience, on a beau subdiviser un algorithme un peu compliqué, ca n'aide pas trop à comprendre comment/pourquoi ca marche.

Code C :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
#include<stdio.h>
 
#define N 624
#define M 397
#define MATRIX_A 0x9908b0df
#define UPPER_MASK 0x80000000
#define LOWER_MASK 0x7fffffff
 
#define TEMPERING_MASK_B 0x9d2c5680
#define TEMPERING_MASK_C 0xefc60000
#define TEMPERING_SHIFT_U(y)  (y >> 11)
#define TEMPERING_SHIFT_S(y)  (y << 7)
#define TEMPERING_SHIFT_T(y)  (y << 15)
#define TEMPERING_SHIFT_L(y)  (y >> 18)
 
static unsigned long mt[N]
static int mti=N+1;
 
/* initializing the array with a NONZERO seed */
void sgenrand(unsigned long seed)
{
    mt[0]= seed & 0xffffffff;
    for (mti=1; mti<N; mti++)
        mt[mti] = (69069 * mt[mti-1]) & 0xffffffff;
}
 
/* generates a random number on [0,0xffffffff] interval */
/* The array must be initialized prior calling this function */
unsigned long genrand()
{
    unsigned long y;
    static unsigned long mag01[2]={0x0, MATRIX_A};
 
    if (mti >= N) {
        int kk;
 
        if (mti == N+1)
            sgenrand(4357);
 
        for (kk=0;kk<N-M;kk++) {
            y = (mt[kk]&UPPER_MASK)|(mt[kk+1]&LOWER_MASK);
            mt[kk] = mt[kk+M] ^ (y >> 1) ^ mag01[y & 0x1];
        }
        for (;kk<N-1;kk++) {
            y = (mt[kk]&UPPER_MASK)|(mt[kk+1]&LOWER_MASK);
            mt[kk] = mt[kk+(M-N)] ^ (y >> 1) ^ mag01[y & 0x1];
        }
        y = (mt[N-1]&UPPER_MASK)|(mt[0]&LOWER_MASK);
        mt[N-1] = mt[M-1] ^ (y >> 1) ^ mag01[y & 0x1];
 
        mti = 0;
    }
 
    y = mt[mti++];
    y ^= TEMPERING_SHIFT_U(y);
    y ^= TEMPERING_SHIFT_S(y) & TEMPERING_MASK_B;
    y ^= TEMPERING_SHIFT_T(y) & TEMPERING_MASK_C;
    y ^= TEMPERING_SHIFT_L(y);
 
    return y;
}

Pour une explication lire ceci.

[koala01]

De mon expérience, on a beau subdiviser un algorithme un peu compliqué, ca n'aide pas trop à comprendre comment/pourquoi ca marche.

Code C :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
#include<stdio.h>
 
#define N 624
#define M 397
#define MATRIX_A 0x9908b0df
#define UPPER_MASK 0x80000000
#define LOWER_MASK 0x7fffffff
 
#define TEMPERING_MASK_B 0x9d2c5680
#define TEMPERING_MASK_C 0xefc60000
#define TEMPERING_SHIFT_U(y)  (y >> 11)
#define TEMPERING_SHIFT_S(y)  (y << 7)
#define TEMPERING_SHIFT_T(y)  (y << 15)
#define TEMPERING_SHIFT_L(y)  (y >> 18)
 
static unsigned long mt[N]
static int mti=N+1;
 
/* initializing the array with a NONZERO seed */
void sgenrand(unsigned long seed)
{
    mt[0]= seed & 0xffffffff;
    for (mti=1; mti<N; mti++)
        mt[mti] = (69069 * mt[mti-1]) & 0xffffffff;
}
 
/* generates a random number on [0,0xffffffff] interval */
/* The array must be initialized prior calling this function */
unsigned long genrand()
{
    unsigned long y;
    static unsigned long mag01[2]={0x0, MATRIX_A};
 
    if (mti >= N) {
        int kk;
 
        if (mti == N+1)
            sgenrand(4357);
 
        for (kk=0;kk<N-M;kk++) {
            y = (mt[kk]&UPPER_MASK)|(mt[kk+1]&LOWER_MASK);
            mt[kk] = mt[kk+M] ^ (y >> 1) ^ mag01[y & 0x1];
        }
        for (;kk<N-1;kk++) {
            y = (mt[kk]&UPPER_MASK)|(mt[kk+1]&LOWER_MASK);
            mt[kk] = mt[kk+(M-N)] ^ (y >> 1) ^ mag01[y & 0x1];
        }
        y = (mt[N-1]&UPPER_MASK)|(mt[0]&LOWER_MASK);
        mt[N-1] = mt[M-1] ^ (y >> 1) ^ mag01[y & 0x1];
 
        mti = 0;
    }
 
    y = mt[mti++];
    y ^= TEMPERING_SHIFT_U(y);
    y ^= TEMPERING_SHIFT_S(y) & TEMPERING_MASK_B;
    y ^= TEMPERING_SHIFT_T(y) & TEMPERING_MASK_C;
    y ^= TEMPERING_SHIFT_L(y);
 
    return y;
}

Pour une explication lire ceci.

Renommes déjà N, M, MATRIX_A, y, kk, et ton code n'a plus vraiment besoin de commentaire (meme s'il serait sans doute aussi pas mal de renommer les TEMPERING_SHIFT_xx en quelque chose de plus explicite )

En outre, les deux boucles étant totalement identiques pourraient être remplacées par une seule fonction, appelée deux fois

[Paul TOTH]

C'est justement pour cela que l'héritage et le polymorphisme existent: pour te permettre d'adapter un comportement particulier à un type d'objets particulier sans avoir à modifier les comportements existants (tout en restant libre, le cas échéant, de les réutiliser)
Les classes mal conçues sont beaucoup plus souvent dues au non respect (ou à une mauvaise compréhension / mise en oeuvre) des principes SOLID dont je parlais la tantot, LSP et SRP en tête

j'allais te demander si tu étais formateur ou enseignant...mais ton CV en ligne bien que datant un peu m'éclaire un peu sur tes prises de positions.

tu as une vision théorique des choses, elle n'est pas fausse en soit, elle est juste en décalage avec la réalité...c'est pour cette même raison que tu annonces sur ton site que s'il n'est pas correctement affiché par mon navigateur, c'est que mon navigateur ne respecte pas les recommandations du W3C..la belle affaire !

et je me permets juste un petit copier/coller de cette source dont je grasse certains passages

Tous les langages permettent de mettre des commentaires, parfois sur une ligne, parfois sur plusieurs, parfois même après une ou plusieurs instructions, pour autant que ce soit à la fin de la ligne (qu'il n'y ait pas d'autre instruction après le commentaire)

Comme les commentaires ne sont purement et simplement pas intégrés dans l'exécutable pour les langages compilés, ni pris en compte pour les langages interprétés, il serait idiot de ne pas s'en servir…

A vrai dire, c'est même une chose dont l'abus ne nuise nullement, bien qu'il soit utile de veiller à les utiliser à bon escient…

Certaines personnes n'hésitent pas à préconiser que les commentaires devraient représenter un tiers des lignes du programme

Je me contenterai pour ma part de vous conseiller d'en mettre suffisemment pour vous permettre de savoir retrouver facilement le but qui était recherché par un bloc d'instruction, ainsi qu'une description sommaire de la logique que vous avez suivie pour y arriver…

Soyez toute fois logique dans l'utilisation des commentaires: commenter une ligne du genre

Code :

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

1
2
variable = variable +1 // incrémente variable

n'a pas énormément d'intérêt…Ne serait-ce parce qu'il ne faut pas sortir de polytechnique pour savoir que si on donne à une variable sa valeur +1, sa valeur aura augmenté de 1…

Un commentaire efficace concernant cette incrémentation serait sans doute d'en préciser la raison…

En outre, j'aurais personnellement tendance à *conseiller* de mettre le commentaire AVANT l'instruction ou le bloc d'instructions auquel il se rapporte… mais ça, ça reste du domaine des goûts et des couleurs…

La raison de ce conseil est toute simple: comme tout un chacun, je lis géralement le texte de haut en bas… je préfère donc savoir ce qui m'attend dans ce que je n'ai pas encore lu plutôt que d'avoir (enfin) une information sur quelque chose que je n'aurais pas compris …

Mais que c'est-il passé depuis que tu as rédigé cet article ? quelle formation as-tu suivi ? Quelle vérité s'est imposée à toi ?

[Loceka]

En outre, les deux boucles étant totalement identiques pourraient être remplacées par une seule fonction, appelée deux fois

Et ça aiderait à la compréhension de la chose ?
En quoi cette boucle for (en dehors du fait d'être utilisée 2 fois, plus ou moins à l'identique) mérite-t-elle d'être externalisée dans une fonction unitaire ? Elle a un sens métier particulier ? Elle sera réutilisée ailleurs que dans cet algo ?

Franchement, tout externaliser dans des fonctions est aussi stupide que [j'ai pas d'idée qui me vient présentement, alors remplacer par un truc très stupide]. Qui plus est, dans un algo comme celui-ci, qui est relativement court, ça perdrait le lecteur plus qu'autre chose.