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

Version imprimable

Voir 40 message(s) de cette discussion en une page

Citation:

Envoyé par Tommy31

:mrgreen: d'accord, mais n'est-ce pas mieux que ceci (que l'on voit d'expérience trop souvent) :

Code:

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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
package ui;

// Imports de la classe
import java.awt.Dimension;
import java.util.ArrayList;

/**
 * Classe modélisant une centrale de co2.
 *
 * @author Hegros
 */
public class VCentraleCo2 extends VFrame {

        /** Contient la liste des cadres */
	private ArrayList listFrames = new ArrayList();
       /** description de la centrale */
	private String description ;
      /** nom de la centrale */
	private String name;		
		

/**
 * Constructeur.
 * param name le nom de la centrale
 * param description la description de la centrale
 */	
	public VCentraleCo2(String name, String description)
	{		
               // affecte les propriétés
		this.name=name;
		this.description =description;
	}
	
       /**
        * Ajoute un autre cadre .
        * @param vframe le cadre à ajouter.
        */
	public void add(VFrame vframe)
	{
		System.out.println("add dans " +name);
		listFrames.add(vframe);
	}
	
     
      /**
        * Supprime un cadre .
        * @param vframe le cadre à supprimer.        */
	public void remove(VFrame vframe)
	{
		listFrames.remove(vframe);
	}
	
       /** 
         * Retourne un cadre selon son index.
         * @param i l'index du cadre à retourner
         * @return le cadre selon l'index fourni
          */
	public VFrame getChild(int i)
	{
		return (VFrame)listFrames.get(i);
	}
	
       /**
        * @return la description de la centrale
        */
	public String getDescription()
	{
		return description;
	}
	
        /**
          * @return le nom de la centrale
          */
	public String getName()
	{
		return name;
	}
	
        /**
         * Crée les controles.
         */
	public void createControls()
	{
		System.out.println("creation des controles de " +name);
	}
	
        /**
          * Créé la vue.
          */
	public void createView()
	{
		System.out.println("creation de la vue " +
								getName() +"-"+getDescription());
		setTitle(getName());			
	}
	
       /**
        * Affiche le nombre de cadres.
        */
	public void print()
	{
		setVisible(true);
		int nbFrame = listFrames.size();
		
		System.out.println("nombre de frame dans " + name + " : "+ nbFrame );											
	}	
} // fin de la classe VCentraleCo2

C'est verbeux, redondant et finalement sans apport révélateur.

Effectivement, de tels commentaires ne sont franchement pas terribles.

Certains commentaires sont inutiles, par exemple:

Code:

// affecte les propriétés

Code:

// Imports de la classe

Les commentaires d'en-tête sont loin d'être complet (la plupart sont essentiellement de simple paraphrase des noms de fonction/paramètres sans spécifier les conditions d'utilisation, le codage des paramètres, etc. Bref pas très utile en l'état), par exemple:

Code:

1
2
3
4
5
6
       /** 
         * Retourne un cadre selon son index.
         * @param i l'index du cadre à retourner
         * @return le cadre selon l'index fourni
          */

26/05/2009, 21h31
hegros

Citation:

Envoyé par gl

Enfin !

Pourquoi t'obstinais-tu alors à essayer de démontrer le contraire ? Ca fait grosso-modo deux semaines que moi et quelques autres ne disons rien d'autre que ceci.

Si on n'a plus le droit de se marrer un peu...En plus je pensais bien que c'était clair dés le début pour les plus expérimentés. Au final, on se rends compte
que tout le monde n'interprète et n'applique pas de la meilleure façon un commentaire.

Sinon des questions intéressantes se sont posées (mais souviron esquive) parce qu'il persiste à dire (sans le démontrer biensûr) que cela a un profit pour la maintenance alors que depuis la nuit des temps on écrit des commentaires et que les couts de maintenance n'ont fait qu'augmenter. Alors soit à moins qu'il veuille dire que sans commentaire les couts seraient multipliés par 10 ou 100 mais bon la pillule me semble un peu grosse intuitivement...
26/05/2009, 21h56
gl

Citation:

Envoyé par hegros

Sinon des questions intéressantes se sont posées (mais souviron esquive) parce qu'il persiste à dire (sans le démontrer biensûr) que cela a un profit pour la maintenance alors que depuis la nuit des temps on écrit des commentaires et que les couts de maintenance n'ont fait qu'augmenter. Alors soit à moins qu'il veuille dire que sans commentaire les couts seraient multipliés par 10 ou 100 mais bon la pillule me semble un peu grosse intuitivement...

Déjà comme tu le fais remarquer, les coûts ont augmenter malgré les commentaires, mais il est difficile de prouver que l'augmentation n'aurait pas été plus importante sans ces commentaires (le contraire est tout aussi difficile à démontrer par ailleurs).

D'autre part, un commentaire intelligent et judicieux a un réel impact. D'expérience, on trouve un nombre important de commentaires totalement inutiles tout comme il manque souvent des commentaires qui auraient pu être utiles (ces deux problèmes pouvant bien sur être présent dans un même source).
26/05/2009, 22h49
Chatanga
Ayons quand même une pensée émue pour l'honnête développeur forcé d'écrire les commentaires suivants pour éviter que le serveur d'intégration n'envoie une décharge électrique dans sa chaise à chaque livraison :
Code:

1 2 3 4 5 6 7 8 9 10 11 /** * @brief Méthode retournant le type. * * Retourne le type. * * @return Le type. */ int getType() { return type; }
:sm:
27/05/2009, 00h44
souviron34
Citation:

Envoyé par hegros

Sinon des questions intéressantes se sont posées (mais souviron esquive) parce qu'il persiste à dire (sans le démontrer biensûr) que cela a un profit pour la maintenance alors que depuis la nuit des temps on écrit des commentaires et que les couts de maintenance n'ont fait qu'augmenter. Alors soit à moins qu'il veuille dire que sans commentaire les couts seraient multipliés par 10 ou 100 mais bon la pillule me semble un peu grosse intuitivement...

J'ai esquivé parce que je fatiguais d'avoir à ressasser la même chose pour tenter de convaincre un borné d'une chose aussi élémentaire... :P

Maintenant, sur le fond, encore une fois je pense que tu confonds plusieurs choses..

La maintenance réelle d'un logiciel n'a rien à voir avec ce qui est inclus dans un contrat de maintenance, à moins que celui-ci ne soit étalé sur 25 ans...

La plupart des gros investissements en logiciel s'étale sur 5, 10, 20 ou 30 ans, et la plupart des gros logiciels met de 2 à 10 ans à s'écrire.

La "maintenance" de ces logiciels consiste donc en plusieurs choses :
1. maintenance "réelle" de la fonctionalité fournie au départ (adaptation à de nouvelles machines, de nouvelles données, etc)
2. ajout de nouvelles fonctionalités
3. retrait ou modification de fonctionalités existantes
4. ré-écriture partielle (ou totale) d'une application
le tout étant en général étalé sur 10-15 ans (pour un soft "relativement peu important") jusqu'à 30-40 ans (pour un très gros soft, vital pour une activité ou une entreprise).

Puisque soi-disant "j'affirme sans démontrer", démontre-moi que les coûts de maintenance ont explosé, et que cela est dû aux commentaires...

Ce que je répète depuis presque 15 pages, c'est que, dans le cadre d'une maintenance "long terme" ou d'une vraie industrie internationale (logiciel pour les constructeurs automobiles, les avions, les fusées, le médical lourd (machines IRM, scanners lourds, radio numérique, etc)) dont les centres de maintenance sont répartis sur les 5 continents, avec à peu près une équipe de maintenance par pays, ou au minimum par continent, il est essentiel qu'il y ait des commentaires dans le code...

Mais que c'est également valable dès que tu tiens à faire quelque chose qui dure un tant soit peu, même si ce n'est pas un "très gros projet", pour toutes les raisons déjà mentionnées : reprise par d'autres, rachat de la société, vente des sources par l'entreprise, ré-utilisation dans d'autres projets, démission / licenciement de l'auteur, changement de responsabilité de l''auteur / de l'équipe...

Quant à l'explosion des coûts de maintenance, si elle existe, étant un vieux con dinosaure je vais dire que c'est de la faute aux jeunes et aux langages objets, aux modélisations et normes à outrance, etc etc :lol:

Plus sérieusement, si cela existe, c'est dû à plusieurs facteurs, mais qui ne sont pas très éloignés de cette caricature :
1. les méthodes et outils style UML, MDA, etc, ISO, Cmmi, etc etc, ont un coût relativement gigantesque : le montant de papier et de temps perdu à mettre en place ce genre de choses, même avec des "méthodes soi-disant agiles", revient globalement au même que la "paperasserie pléthorique" mentionnée dans le Manifeste Agile à propos des anciennes méthodologies..
2. le fait d'utiliser "à toutes les sauces" des méthodes affublées d'Agile font croire que l'on a résolu le problème de la traduction / prise en compte des besoins, alors que l'on voit ici-même tous les jours que l'on retombe toujours dans les mêmes écueils, c'est à dire par exemple faire faire le travail d'ergonomes ou de graphistes par des informaticiens, qu'on les appelle MOA ou autres... (voir le pourquoi de ma signature)
3. Le "jeunisme" et la course à la dernière technologie en vogue font ré-écrire des applications qui n'avaient aucun besoin d'être ré-écrites, et génèrent un surcoût absolument gigantesque (au moins 100%, puisque on change tout :"le C c'est archaique, faut faire du C++", "X11 c'est archaique faut faire du Qt ou du Java").
4. L'illettrisme et la moindre culture générale croissant, la "technicité" des jeunes croissant, les modèles de conception/d'architecture devant correspondre à cette course se perdent dans / font perdre de vue les besoins essentiels d'une architecture logicielle : la simplicité et la fonctionalité.. (comme nous l'avions discuté avec Garulfo dans un autre débat, le "procédural" se fixe sur la fonctionalité, "l'objet" sur le relationnel...)
5. Le fait de se reposer sur des technologies pas vraiment éprouvées, et des OS peu stables (M$ change tous les 2 ans d'OS, et même Linux est beaucoup moins stable que ne l'étaient les Unix avant lui) entraîne des surcoûts importants.
6. La technologie évoluant vite, les décisions sont de plus en plus prises par des administratifs / CEO ne connaissant guère les conséquences de ces décisions, qu'ils prennent plutôt parce que c'est le "buzz-word" du moment... mais qui justement impliquent dans beaucoup de cas la ré-écriture partielle ou totale d'un code qui marchait pourtant..
7. J'en oublie certainement...
En tous cas, ce n'est certainement pas dû aux commentaires, et de bons commentaires ne peuvent que diminuer ce coût...

8-)
27/05/2009, 09h29
white_tentacle

Citation:

C'est normal le code n'est pas fini je n'ai pas tout implémenté sinon j'aurais déjà publié l'article... c'est un départ en plus des petits fichiers .java j'en ai pleins des comme cela c'est un choix de découpage.

Tu écris tes méthodes avant de définir leur contrat ? :fessee:

Citation:

Ensuite vous pouvez essayer de trouver un commentaire pertinent pour ce genre de méthode puisqu'à priori vous êtes connaisseur moi j'en ai pas trouvé !

Documente le contrat de ta fonction
27/05/2009, 09h53
el_slapper
Citation:
Envoyé par souviron34

(.../...)

les méthodes et outils style UML, MDA, etc, ISO, Cmmi, etc etc, ont un coût relativement gigantesque : le montant de papier et de temps perdu à mettre en place ce genre de choses, même avec des "méthodes soi-disant agiles", revient globalement au même que la "paperasserie pléthorique" mentionnée dans le Manifeste Agile à propos des anciennes méthodologies..

le fait d'utiliser "à toutes les sauces" des méthodes affublées d'Agile font croire que l'on a résolu le problème de la traduction / prise en compte des besoins, alors que l'on voit ici-même tous les jours que l'on retombe toujours dans les mêmes écueils, c'est à dire par exemple faire faire le travail d'ergonomes ou de graphistes par des informaticiens, qu'on les appelle MOA ou autres... (voir le pourquoi de ma signature)

Le "jeunisme" et la course à la dernière technologie en vogue font ré-écrire des applications qui n'avaient aucun besoin d'être ré-écrites, et génèrent un surcoût absolument gigantesque (au moins 100%, puisque on change tout :"le C c'est archaique, faut faire du C++", "X11 c'est archaique faut faire du Qt ou du Java").

L'illettrisme et la moindre culture générale croissant, la "technicité" des jeunes croissant, les modèles de conception/d'architecture devant correspondre à cette course se perdent dans / font perdre de vue les besoins essentiels d'une architecture logicielle : la simplicité et la fonctionalité.. (comme nous l'avions discuté avec Garulfo dans un autre débat, le "procédural" se fixe sur la fonctionalité, "l'objet" sur le relationnel...)

Le fait de se reposer sur des technologies pas vraiment éprouvées, et des OS peu stables (M$ change tous les 2 ans d'OS, et même Linux est beaucoup moins stable que ne l'étaient les Unix avant lui) entraîne des surcoûts importants.

La technologie évoluant vite, les décisions sont de plus en plus prises par des administratifs / CEO ne connaissant guère les conséquences de ces décisions, qu'ils prennent plutôt parce que c'est le "buzz-word" du moment... mais qui justement impliquent dans beaucoup de cas la ré-écriture partielle ou totale d'un code qui marchait pourtant..

J'en oublie certainement...

En tous cas, ce n'est certainement pas dû aux commentaires, et de bons commentaires ne peuvent que diminuer ce coût...

8-)
mmmmh.....l'absence de méthode peut être parfois très dommageable aussi. Les ergonomes, les vrais, ne sont pas tous talentueux(certains se limitent à répeter que le standard, c'est que les boutons doivent être en bas à droite, et puis c'est tout). Le jeunisme ne m'empêche pas de refondre une chaine COBOL de 37 ans d'âge.....en COBOL, donc toujours sur la même plateforme totalement rôdée.

Pourtant, chez nous aussi, les frais de maintenance augmentent aussi. Le seul point que tu cites et qui s'y applique(la MOA qui ne connait pas son boulot) a toujours existé.

Tout simplement, parcequ'en partant toujours du même besoin(terme mensuel pour envoyer les courriers au client et faire la compta), on fait toujours plus de choses(on rajoute un audit comptable par çi, un contrôle fiscal par là, une obligation règlementaire sous le tapis et un éclatement plus fin des codes bilans par dessus le tout, sans compter les innombrables innovations du marketing).

Donc, toujours sur la même chaine, on gère des choses de plus en plus complexes. Fatalement, s'y retrouver devient de plus en plus difficille. Même une chaine parfaite, si elle fait des miliards de trucs, devient difficille à maintenir, ne serait-ce que pour des raisons de volumétrie des tests de non-regression.

Et c'est là qu'on se retrouve : un commentaire astucieux peut faire gagner beeeeeeaucoup de temps. Je reprends là mon exemple de la limite de taille du montant. Quand je suis tombé sur un vague AND NOT MONTANT > 100000000, sans commentaire, sans rien, au milieu d'une condition à la noix, j'ai bien assez vite compris qu'il y avait une limite de montant pour l'édition du TIP. Seulement, fallait-il reconduire la règle? Pourquoi diable était-elle là? Alors j'ai fouillé, les gens des métiers ont fouillé, et après beaucoup de temps, on en est arrivé à la conclusion que c'était une limite technique qu'il fallait reconduire. Alors que le commentaire "limite technique - taille maximale du montant sur le TIP" aurait permis de conclure en quelques minutes.
27/05/2009, 12h07
thomas9501

Bien sûr que oui il faut commenter son code. Que ce soit pour les personnes qui passent derrière ou même pour nous si on le reprend plus tard ...
27/05/2009, 12h31
souviron34

Citation:

Envoyé par el_slapper

mmmmh.....l'absence de méthode peut être parfois très dommageable aussi.

Je n'ai jamais dit le contraire.. :D

Il faut bien entendu une méthode..

Mais encore une fois, comme pour tout ce qui est du logiciel (y compris le sujet de ce thread), le bon sens prime, et non le pied de la lettre de la norme...

je constate juste que on modèlise des modèles de modèles de modèles de soft...

Forcément ça prend de la place, du temps, et donc de l'argent..

Je ré-itère que les trucs comme ISO ou CMMMi sont des générateurs de papier, de temps perdu, et n'augmentent en rien l'assurance que le produit correspond à ce qui était demandé.. Tout au plus cela assure que l'on reproduira la même chose avec le même processus... Mais quand on voit ce qu'il faut pour les mettre en oeuvre, et passer les certifications, c'est certainement une sacrée source de dépenses en plus...

Citation:

Envoyé par el_slapper

Les ergonomes, les vrais, ne sont pas tous talentueux(certains se limitent à répeter que le standard, c'est que les boutons doivent être en bas à droite, et puis c'est tout).

De même que les informaticiens.... :P

Simplement, chacun son métier.....

Et justement, si il y a des leçons à tirer des "vieux dinosaures", c'est de ne pas répéter les mêmes erreurs....

Citation:

Envoyé par el_slapper

Le jeunisme ne m'empêche pas de refondre une chaine COBOL de 37 ans d'âge.....en COBOL, donc toujours sur la même plateforme totalement rôdée.

Ce que je voulais dire, c'est que, que ce soit par formation (que des "nouveaux" langages et concepts appris), par usage (auto-formation, employabilité immédiate sur le "hot topic" du moment, enthousiasme pour tel ou tel truc "nouveau"), par "gossip" et tendances de modes (via le net, via la classe, via les potes, via les forums comme ici), par "ignorance" ou "croyance" des administratifs et RH, l'introduction de nouveaux langages/concepts n'arrête pas (ce qui, en soit est une bonne chose) , mais au rythme des annonces "marketing" et des modes, ce qui en fait une mauvaise.

Regarde juste sur les 8 dernières années pour les sites Web : entre ASP, Java, Flash, .Net, C#, et j'en passe pas mal, cela fait pratiquement de 12 à 15 "modes" de langages...

Et il suffit qu'un nouveau chef de projet / directeur technique ait l'oreille plus attentive à tel ou tel (parce qu'il vient de le découvrir, parce qu'il n'y a que celui-là qu'il a utilisé, etc etc), et que ce n'était pas celui de la boîte, et hop !! on change..

D'où un surcoût gigantesque...

Et à mon avis c'est la source principale de l'explosion des coûts...

ps : et un à-côté ayant les mêmes racines et allant dans le même sens, c'est les langages utlisés pour faire autre chose que ce à quoi ils étaient destinés, poussant (par force, puisqu'ils n'étaient pas faits pour ça) à des constructions complexes, ou des coûts élévés (besoin de plus de mémoire, de plus de HD, de plus de vitesse, de plus de coeurs, ...). Un exemple "simple" : Java. Java était fait par SUN pour les IHM, pour unifier ce qui étaient sous M$ (Windows API) et sous les autres OS (X11 / Motif était le standard). Sa sphère aurait donc dû rester sur les IHM. Mais la concommittance de la mode, de l'enseignement, et des méthodologies OO en ont fait un langage "généraliste", sauf que les concepts sont mal enseignés ?? digérés ?? et qu'il suffit de regarder dans le forum conceptions pour se rendre compte du nombre (effarant) de "mauvaises" modélisations, ou l'IHM est incluse dans les métiers ou réciproquement, sans qu'il y ait de véritable séparation en couches.

Citation:

Envoyé par el_slapper

Pourtant, chez nous aussi, les frais de maintenance augmentent aussi. Le seul point que tu cites et qui s'y applique(la MOA qui ne connait pas son boulot) a toujours existé.

Faux..

Les postes de MOA ne datent que d'il y a 6 ou 7 ans (d'ailleurs, le terme n'existait même pas avant 2000).

Mais , ce qui rejoint le point précédent, c'est aussi alors que le mouvement général depuis le début de l'informatique était vers une unification (langages forts et peu nombreux, OS tendant vers Unix, échange de documents unifiés par HTML, échange réseau unifié par HTTP, échange de fichiers unifiés par FTP), on a assisté ces 15 dernières années à un processus inverse, avec des langages de plus en plus nombreux, souvent relativement éphémères ou incompatibles entre eux, ou disponibles uniquement sur une seule plateforme (suivez mon regard)..

Quant aux méthodologies, ce n'est pas mieux...

Citation:

Envoyé par el_slapper

Tout simplement, parcequ'en partant toujours du même besoin(terme mensuel pour envoyer les courriers au client et faire la compta), on fait toujours plus de choses(on rajoute un audit comptable par çi, un contrôle fiscal par là, une obligation règlementaire sous le tapis et un éclatement plus fin des codes bilans par dessus le tout,

Sans doute, mais plus volontiers ceci :

Citation:

Envoyé par el_slapper

sans compter les innombrables innovations du marketing).

Pour le reste, nous sommes d'accord...
:D
27/05/2009, 13h29
Vlade

Commentez son code en utilisant UML

Je vais juste parler des commentaires dans le code Java et de l'utilisation d'UML dans une approche UML Structure model du projet entier et pas dans le cadre historique des vues UML.

Pour moi il faut toujours mettre des commentaires dans le code afin de rajouter des informations pertinentes. Je dirai même qu'il faudrait en mettre beaucoup plus. Le problème est que cela polue la lisibilité du code et donc en mettant trop de commentaire on fini par le rendre moins visible. J'ai eu un débat sur ce sujet avec un grand groupe Allemand le mois dernier. Il voulais utiliser maven, une approche de développement continue et faire très très peu d'UML juste pour la documentation et ne pas se prendre la tête à deux mains dans un process de type RUP.

Et là je leur ai proposé de marquer les informations indispensables dans le code mais surtout d'utiliser la structure UML du model et quelques diagrammes commentez pour faire le reste de la documentation. On a été si loin que dorénavant ils vont tout documentez et laisser un code propre et lisible .

Comment on a fait ?:
1. L'idée est de créer quelques diagrammes de Classe sur des points stratégiques nécessitant une documentation approfondi. Ils ont donc reversé le projet en cours, crée des diagrammes et rajouter des notes graphiques.
2. Ensuite le projet a continuer à évoluer mais ils ne voulaient pas passer du temps à modeliser car c'est des codeurs, mais ils voulaient pas non plus perdre la qualité de la documentation. Alors le concept du merge incremental a été utlisé. Il s'agit à un moment T du développement de merger le model UML et le code java. A ce moment et de manière transparente tous les diagrammes crée sont remis à jour automatiquement.
3. En UML ont explique le comment mais pas le pourquoi. Pour inclure cette explication ont a décidé d'utiliser les eannotations sur les classifiers (je veux dire classe, interface, et énumeration), les packages, les associations etc.....L'eannotation est une documentation tapez à la main qui lorsque le dévelopeur click sur un objet sur le diagramme ouvre une vue documentation à côté.

Voilà décrite de manière simple ce que l'un des plus gros développeur de solution java en Europe fait aujourd'hui afin de rendre lisible sont code, de documenter en temps réel ses projets, d'ajouter des informations pertinentes et immédiatement utlisable entre tous les gens de l'équipes (le model est sur SVN) et aussi d'umeliser sont projet afin d'en tirer tous les avantages du MDD en cas de refonte du système lors d'un upgrade ultérieur.

Pour informations les développeurs ne connaissent pas UML, ils ont juste reverser les diagrammes et rajouter des commentaires graphiques. Ensuite il ont écrit leur point de vue dans le model dans le fénétre documentation. Ceci a nécessité 2 heures de formation pour la prise en main de l'outil. En plus on a distingué deux type d'utlisateurs chez Omondo. Des modeleurs classiques et des viewers du modèle qui utilisent juste UML pour la documentation. La license viewer est égal à 10% du prix de la licence modeleur. Il n'y a donc plus de raison économique à ne pas documentez en profondeur son projet avec les méthodes moderne de développement.
27/05/2009, 13h43
Saten

Je pense que tout bon programmeur qui se respecte est d'accord sur le fait que :

- commenter les 3/4 de son code est inutile (ou alors je veux même pas voir la tête du programme^^);
- expliquer en quelques mots à quoi sert une fonction complexe et si besoin les contraintes qu'elle subit;
- expliquer des choix étranges lorsques ceux-ci sont devenus nécessaires à cause de diverses contraintes;
- faire des remarques pour les futurs dév.;

Après, c'est du gain de temps, mais bon, honnêtement, trop commenter son code, c'est le rendre très lourd à lire, donc pas efficace pour un sou, et ne rien mettre, c'est risquer que le codeur qui suit soit mette du temps à analyser tout de partout ou soit qu'il se plante...
27/05/2009, 13h57
Leonhart

[QUOTE=Saten;4344391
Après, c'est du gain de temps, mais bon, honnêtement, trop commenter son code, c'est le rendre très lourd à lire, donc pas efficace pour un sou, et ne rien mettre, c'est risquer que le codeur qui suit soit mette du temps à analyser tout de partout ou soit qu'il se plante...[/QUOTE]

Comment tout résumé en quelques lignes !

Il est vrai que quand on se retrouve avec 3000 lignes de C# à débuggé et qu'il n'y a pas de commentaire pertinent ... ouille ouille ouille !

Pour savoir ce qui est pertinent ou non dans son code, le reprendre deux semaines après l'avoir écrit et ajouté les réponses à toutes les questions que l'on se pose alors ... 100% efficace :ccool:
27/05/2009, 14h48
white_tentacle

Citation:

Java était fait par SUN pour les IHM, pour unifier ce qui étaient sous M$ (Windows API) et sous les autres OS (X11 / Motif était le standard).

Je crois que tu te fourvoies un peu sur les objectifs initiaux de java. Ce n'est notamment pas anodin si la machine virtuelle java peut fonctionner en 16 bits (cible processeurs ARM).

Après, il est clair qu'il y a eu buzz sur java, comme il y a buzz sur .net (même si C# a beaucoup de qualités).
27/05/2009, 20h48
Garulfo

Citation:

Envoyé par hegros

[...]
est-ce que ce commentaire 'implémentation du pattern composite pour la vue principale' est pertinent ?[...]

Non il ne l'est toujours pas. Dans ce commentaire tu exprimes comment tu as implémenté quelque chose et toujours pas ce que ce quelque chose fait. Tu peux ajouter cette précision dans le cas où elle serait pertinente. C'est rarement le cas.
27/05/2009, 20h48
hegros

Citation:

Envoyé par white_tentacle

Tu écris tes méthodes avant de définir leur contrat ? :fessee:

C'est dû au fait que je n'écris pas un contrat pour toutes les opérations en principe simplement les plus importantes et critiques bien que le faire pour tous reste possible et surement plus complet.

Voilà un exemple de début de contrat pour le fichier java en question

Citation:

Référence croisée : cas d'utilisation particulier initialisation système
Opération : Add(VFrame vFrame)
Pré-condition :
Un objet ArrayFrames existe
Post-condition :
L'objet vFrame a été ajouté à ArrayFrames
Exception :
Plus de mémoire

Citation:

Référence croisée : cas d'utilisation particulier initialisation système
Opération : remove(VFrame vFrame)
Pré-condition :
Un objet ArrayFrames existe
Post-condition :
L'objet vFrame a été supprimé de ArrayFrames
Exception :
L'objet vFrame n'est pas dans l'objet ArrayFrames

Cela revient un peu à ce que je disais à milie, ce sont c'est des faux commentaires parce que écrit plus 'formellement'.

Citation:

Envoyé par white_tentacle

Documente le contrat de ta fonction

Sauf que ce n'est plus de documenter d'écrire un contrat, c'est spécifier , concevoir et documenter prends l'exemple avec l'opération CreateControls. Il va falloir ajouter des boutons des labels mais bon la classe n'a encore de propriétés de ce type car pas totalement conçu mais on attends pas que se soit totalement fini pour implémenter une base d'architecture.

Ce serait le tip-top de tomber sur une équipe qui commente toutes les méthodes de toutes les classes de toutes les unités de tous les modules de tous les systèmes avec des contrats de fonction/opération:P
27/05/2009, 22h02
Chatanga

Citation:

Envoyé par Vlade

Pour moi il faut toujours mettre des commentaires dans le code afin de rajouter des informations pertinentes. Je dirai même qu'il faudrait en mettre beaucoup plus. Le problème est que cela polue la lisibilité du code et donc en mettant trop de commentaire on fini par le rendre moins visible"

Le consensus qui semble se dégager de cette discussion est que des commentaires ciblés et pertinents sont hautement appréciables dans un code mais que la nécessité d'en arriver à noyer ce même code avec sa prose suggère plutôt un code lourdingue fondamentalement problématique. Un commentaire n'est pas un tutoriel.

Citation:

Envoyé par Vlade

ils ne voulaient pas passer du temps à modeliser car c'est des codeurs

"le code" = code model = le modèle d'implémentation.

Donc coder, c'est modéliser. C'est d'ailleurs pour cette raison qu'il est possible d'afficher des diagrammes UML de fichiers sources en langage objet sans efforts. A la rigueur, hors le Java qui est marié avec UML depuis le début, des langages comme le C++ ont besoin d'une certaine conversion mais non d'une réelle rétro-ingénierie puisqu'ils offrent le même niveau d'abstraction. Ces développeurs qui manquent de temps font ainsi à leur insu de la modélisation. Sauf peut-être s'ils sont persuadés que l'héritage se rapporte à leur grand parents et le polymorphisme à certaines espèces de caméléons. Dans ce second cas, les diagrammes UML ne feront qu'illustrer le désastre : rectangle de classes affichant ses 500 méthodes sur 2 feuilles A3, relations entre classes figurant une dense toile d'araignée, etc.

Dessiner sous des outils comme RSA des rectangles désignant des classes c'est coder ces mêmes classes, les diagrammes UML n'étant que des vues sur le modèle de code. Pour être précis c'est même sous-coder puisque les définitions de méthodes sont rarement modélisées en UML (pour un intérêt il est vrai généralement mince). Ces diagrammes restent néanmoins utiles comme documentation dans la mesure où ils permettent une vue "aérienne" d'un code en cachant certains aspects et en mettant l'accent sur d'autres, y compris via des notes, mais encore faut-il comprendre la notation UML ! Je ne vois pas comment des "développeurs [qui] ne connaissent pas UML" peuvent commenter des diagrammes qu'ils ne savent pas lire eux-même.

Il est aussi possible de définir d'autres modèles de plus haut niveau, par exemple des modèles de composants de niveau architectural ou encore des modèles systèmes à la fois plus abstraits et plus décorélés du code, le tout avec des capacités ou non de transformations plus ou moins automatiques façon MDA. Ces modèles ont (potentiellement) une vraie valeur ajoutée par rapport au modèle physique du code mais leur obtention par rétro-ingénierie relève d'un vrai travail d'analyse et non de trois clics de souris.

Pour finir, il me semble qu'existe des alternatives simples et gratos à Omono pour l'usage que tu sembles en faire. Doxygen peut ainsi simplement générer des diagrammes UML de navigation assez pratique pour du code C++ et Java. Pour du Java pur et afin d'extraire quelque chose de plus complet, j'aime personnellement bien utiliser NetBeans.
27/05/2009, 22h34
hegros

Citation:

Envoyé par Garulfo

Dans ce commentaire tu exprimes comment tu as implémenté quelque chose et toujours pas ce que ce quelque chose fait.

C'est quand même écrit 'pour la vue principale', c'est ce que fait cette classe (VCentraleCo2.java) en version courte biensûr.

En même temps la vue principale fait pleins de choses puisque c'est l'écran de surveillance/contrôle où sont transmises les informations/vues concernant la régulation d'un système de co2 dans des parkings sous-terrain (c'est moi qui l'ai imaginé :mrgreen: )

Il y a aussi le nom du package qui nous situe dans la couche user interface cela identifie que ce quelque chose se fait dans l'écran :oops:

Ca refroidi ou ca chauffe alors ?
28/05/2009, 00h38
Vlade

UML et documentation

Réponse pour Chatanga qui lance le débat, merci à lui :ccool:

Citation:

Dans ce second cas, les diagrammes UML ne feront qu'illustrer le désastre : rectangle de classes affichant ses 500 méthodes sur 2 feuilles A3, relations entre classes figurant une dense toile d'araignée, etc.

Il y a un filtre que l'on peut appliquer sur son diagramme et ne montrer que les méthodes importantes. On peut aussi faire des vues et autant que l'on veut avec des petits diagrammes ne montrant que l'information pertinente dans le contexte de la vue que l'on explique. Le diagramme peut être tout petit de la taille d'un carré de 10 cm et avoir toute la vue.

Citation:

mais encore faut-il comprendre la notation UML ! Je ne vois pas comment des "développeurs [qui] ne connaissent pas UML" peuvent commenter des diagrammes qu'ils ne savent pas lire eux-même.

Un reverse d'un projet est toujours lisible :mouarf: Il faut pas pensez que les développeur comprennent rien aux architecture logiciel. Le développeur ne fait de plus des nouveaux diagrammes dans mon exemple il ajoute juste des eannotations qui sont considérées comme de la documentation projet dans le métamodel. C'est un travail facile du niveau d'un bac. Tout le monde peut le faire même sans connaître UML.

Citation:

Pour finir, il me semble qu'existe des alternatives simples et gratos à Omono pour l'usage que tu sembles en faire. Doxygen peut ainsi simplement générer des diagrammes UML de navigation assez pratique pour du code C++ et Java. Pour du Java pur et afin d'extraire quelque chose de plus complet, j'aime personnellement bien utiliser NetBeans.

Oui, il y a des alternatives, mais si on utilise Eclipse alors cela vaut-il la peine d'économiser quelques milliers d'euro en n'achetant du logiciel mais en utlisant de l'open source ? Non, pour moi cela ne vaut pas la peine car le coût logiciel de développement dans un projet est de l'ordre de 1% du projet total or il est critique.

Je comprend pas les intégrateurs qui sont les premiers à facturer mais sans réellement apporter de la qualité de reporting.
28/05/2009, 02h17
Garulfo

Citation:

Envoyé par hegros

C'est quand même écrit 'pour la vue principale'[...]
Ca refroidi ou ca chauffe alors ?

Mais tu ne parles que de ton code et en terme d'informaticien. Ce n'est pas le but du commentaire. En tout cas, je ne veux pas te paraître scholastique ni sembler te donner une leçon. Le commentaire qui se place en entête d'une fonction, par exemple, n'a pas pour but d'expliquer ce que le développeur de la fonction a fait, mais ce qu'il devait faire. Ce commentaire est notamment utilisé par l'équipe de qualité pour tester le comportement de la fonction dans un but de vérification. Si le processus de vérification est fait correctement, ce qui implique la réussite des tests mais sans s'y limiter, on peut considérer qu'en bout de ligne le commentaire reflète bien ce que le développeur a écrit ! Donc, on pourra alors dire que c'est ce qu'il a fait. Mais il n'a pas été écrit dans ce but. J'espère que tu saisis la nuance ;)

En tout cas, pour moi la discussion a assez durée. Elle tend à m'ennuyer. ^_^
28/05/2009, 09h18
white_tentacle

Citation:

Référence croisée : cas d'utilisation particulier initialisation système
Opération : Add(VFrame vFrame)
Pré-condition :
Un objet ArrayFrames existe
Post-condition :
L'objet vFrame a été ajouté à ArrayFrames
Exception :
Plus de mémoire

La précondition n'apporte strictement rien. Evidemment que ArrayFrames existe, sinon, on se prend une NullPointerException (et ça, c'est lié au langage, pas besoin de le préciser).

Par contre, je suis à peu près sûr que ça va merder quelque part ailleurs si tu passes un VFrame null (et au minimum, que ça n'a pas de sens), et pourtant, tu ne le mets pas dans la précondition du Add...

Le bon contrat c'est :

Citation:

pre :
vFrame != null
post :
frames.size() == previous frames.size() + 1
frames.last() == vFrame

Voir 40 message(s) de cette discussion en une page