Commenter le code

Version imprimable

03/08/2006, 08h18
mambo

Commenter le code

Bonjour tlm,

Est ce que quelqu'un saurait s'il existe des méthodologies de commentaires du code?

Merci.
03/08/2006, 08h27
superspag

perso, j'utilise d'oxygen...
1/ les codes sont clairement commentés
2/ les doc générées sont claires et bien illustrées

Bon ok, faut dire aussi que je n'ai jamais rien essayé d'autre :aie:
03/08/2006, 08h38
mambo

Tu pourrais me dire un peu plus sur d'oxygen?
03/08/2006, 08h53
superspag

ils en parlent un peu là : http://fr.wikipedia.org/wiki/Doxygen

Le site officiel : http://www.doxygen.org/

Il y a pas mal d'exemples sur ces sites.
En gros, en respectant les formes de Doxygen, non seulement tu commentes ton code de manière claire et complete, mais en prime, tu peux utiliser le programme Doxygen qui va analyser tes sources et te générer une documentation au format que tu veux... HTML par exemple ;)
03/08/2006, 08h54
Invité

Citation:

Envoyé par mambo

Tu pourrais me dire un peu plus sur d'oxygen?

doxygen, c'est un outil qui scrute les commentaires dans ton code et génere une doc qu format que tu lui demande (HTML, man, etc...) un peu a la maniere de la javadoc. tu devrais aller voir sur le site officiel... par ailleurs, le fichier d'aide en local (.hlp) quand tu installe doxywizard est tres complete quant à la syntaxe a respecter...
03/08/2006, 09h25
mambo

Merci bcp à tous les deux :) je vais m'y mettre.
03/08/2006, 09h29
Eusebe

Tu trouveras un tuto là :
http://cyberzoide.developpez.com/java/doxygen/

D'accord, c'est pour java, mais pour commenter, ça change pas beaucoup ;)
05/08/2006, 09h58
mambo

Est ce qu'il y a d'autres façons de faire?

J'ai besoin de 2 ou 3 méthodologies pour faire une comparaison.

Merci d'avance.

Je suis mitigé par rapport à Doxygen. J'ai du voir trop de cas ooù il était mal utilisé. En particulier, il a tendance à faire du code trop commenté. Pour moi, mes priorités en terme de commentaires sont dans l'ordre :

1 - Un document externe au code qui décrit la philosophie d'une module, comment les classes qui le composent intéragissent les unes avec les autres, si c'est une bibliothèque, un exemple typique d'utilisation, des dessins...

2 - De la documentation des points sensibles de l'implémentation(*), des astuces, des présupposés que l'on fait à un endroit dans le code et qu'on n'a pas voulu/pu vérifier par un assert...

3 - La documentation de toutes les fonctions d'interface

C'est clair que pour une bibliothèque destinée à être utilisée de manière externe, l'ordre serait plus 1, 3, 2. Pour de l'interne, le 3, bien que très utile, est à mon sens un peu moins critique.

Or, ce que permet doxygen, c'est le point 3, et uniquement celui là(**). Et j'ai vu trop de gens avoir bonne conscience en ayant bien fait et paufiné le 3, et en ayant oublié les 2 autres, mais bon, ils avaient fait Doxygen, ils ne pouvaient pas avoir mal fait...

Regarde par exemple http://libxmlplusplus.sourceforge.ne...hierarchy.html (pur point 3) et la doc de Qt (exemple : http://qt.developpez.com/doc/4.1/qcolor/ ) point 1 et 3.

Le seul reproche que je peux faire à Doxygen pour le point 3, c'est qu'il peut avoir tendance à rendre les commentaires un peu verbeux, et le code source risque alors d'être perdu entre les commentaires. Un bon éditeur permet de remédier à ça. Il n'en reste pas moins que c'est un bon outil, que j'utilise régulièrement, mais en mode minimaliste.

(*) Ne pas oublier ce conseil : Quand on voit un commentaire dans l'implémentation, soit il paraphrase le code sans rien apporter de plus, dans ce cas l'enlever, soit il signale une subtilité, dans ce cas, chercher par tout moyen à l'enlever par du refactoring.
Exemple (con, mais c'est juste pour l'exemple):
Code:

1 2 3 4 5 double calculeSalaire() { // Salaire de base + prime de risque (taux de base * coeef de durée de risque) return 100 + 3*dureeDeTravail*0.12; }
Peut se remplacer par :
Code:

1 2 3 4 5 6 7 8 9 10 11 double const coeffDeDureeDeRisque = 0.12; double const tauxHoraireDuRisque = 3; double const salaireDeBase = 100; double calculePrimeRisque() { return tauxHoraireDuRisque * (dureeDeTravail * coeffDeDureeDeRisque); } double calculeSalaire() { return salaireDeBase + calculePrimeRisque(); }
0 commentaires, mais code mieux commenté !

(**) Il donne des moyens d'intégrer des éléments de type 1 à l'intérieur du type 3, mais de là à dire qu'il peut faire du 1...

05/08/2006, 11h20
plegat

Salut,

Citation:

Envoyé par JolyLoic

et la doc de Qt (exemple : http://qt.developpez.com/doc/4.1/qcolor/ ) point 1 et 3.

J'ai dû rater un truc, mais il me semble que c'est exactement la remarque que tu fait pour Doxygen:

Citation:

Envoyé par JolyLoic

(**) Il donne des moyens d'intégrer des éléments de type 1 à l'intérieur du type 3, mais de là à dire qu'il peut faire du 1...

La description détaillée de la classe est fournie dans la doc de la classe, éventuellement avec les schémas d'héritage ou d'interfaçage ou d'autre chose...

Ou alors je n'ai pas bien compris la différence entre les deux liens exemples...

Je dis ça parce qu'un outil qui ferait ton point 1) m'intéresserait grandement (à moins qu'il y ait un paramètre magique dans Doxygen pour virer les descriptions des propriétés et méthodes...).
05/08/2006, 12h10
Charlemagne

J'avais essayé Doxygen y'a 2-3 ans et j'avais été quand même décu car il buttait à pas mal d'endroits où la syntaxe C++ devenait trop compliquée pour lui et je trouvais la présentation par défaut pas terrible.

Je lui avais largement préféré DocJet.
Il est malheureusement payant mais la version démo permet 300 commentaires, ce qui est déjà pour un projet de taille appréciable.
Voici les avantages que je lui trouve par rapport à Doxygen
- comprends mieux la syntaxe C++
- présentation plus jolie
- s'intègre à Visual, facile d'utilisation
- syntaxe concise des commentaires
- génère plusieurs formats (HTML, Windows Help...)

Je trouve qu'il s'acquitte plutôt bien des points 1 et 3 soulevés par Loïc.
Voici par exemple la doc HTML que j'ai générée avec Docjet sans me donner beaucoup de mal (présentation par défaut). Il y a environ 300 commentaires, mais toutes les fonctions de mon projet ne sont pas commentées.
http://www.ient.rwth-aachen.de/team/...contentsf.html

Citation:

Je dis ça parce qu'un outil qui ferait ton point 1) m'intéresserait grandement (à moins qu'il y ait un paramètre magique dans Doxygen pour virer les descriptions des propriétés et méthodes...).

Avec Docjet il est possible de mettre des commentaires par défaut. Pour faire ce que tu veux il suffit de mettre la commande 'secret' par défaut.
05/08/2006, 14h37
superspag

Perso, je m'en sert surtout pour les interfaces... Savoir à quoi servent les fonctions, quelles sont les parametres, quelles sont leurs types, les valeurs de retour, les preconditions, les types d'exception, etc...

Par contre dans le code... je ne suis pas du genre à en foutre des tartines. JE suis plutot d'accord avec JolyLoic. Point trop n'en faut ! :mouarf:
05/08/2006, 14h52
JolyLoic

Citation:

Envoyé par plegat

J'ai dû rater un truc, mais il me semble que c'est exactement la remarque que tu fait pour Doxygen:

Effectivement. Les développeurs de Qt on fait l'effort de faire le point 1. C'est probablement ce qui fait de la doc de Qt une des meilleures que j'ai lu à ce jour.

Pour ça, ils ont utilisé Doxygen, afin de mèler ce point et le point 3. Ce que je voulais dire, c'est que bien que Doxygen ait pu leur laisser faire le point 1, il n'a assurément pas aidé à le faire. Je pense qu'ils auraient eu plus facile avec un simple traitement de texte ou un wiki.
07/08/2006, 13h51
BigNic

Citation:

Envoyé par JolyLoic

(*) Ne pas oublier ce conseil : Quand on voit un commentaire dans l'implémentation, soit il paraphrase le code sans rien apporter de plus, dans ce cas l'enlever, soit il signale une subtilité, dans ce cas, chercher par tout moyen à l'enlever par du refactoring.

Je ne suis pas tout à fait d'accord avec toi, souvent cela indique des raisons fonctionnelles du pourquoi on fait cela. En tout cas moi c'est souvent ce que je fait. En effet pour des développeurs ayant une forte composante métier (pas des développeur système quoi), souvent les subtilités du code sont amené par des raisons fonctionelles; or quand un collègues passe derière toi c'est souvent cette expertise métier qui lui manque et il est bon de lui indiquer dans le code.
sinon pour le 1) en fait cela dépend des habitudes de ta boite. Personnellement je bosse dans une boite ou nous n'avons pas l'habitude d'écrire de la doc. Donc quand je suis arrivé, plein d'orgeuil et de naiité, je me suis dit oi je vais en faire et leur montrer l'utilité de la doc. En 6 ans rien à changé d'un yota, personne ne lit mes docs, ils sont tellement habitué à ce qu'il n'y en ai pas qu'ils se posent même pas la question de savoir s'il elle existe. Il viennent tous getillement me demander: " et ça, à quoi cela sert ?".
Alors que si je leur met du commentaire dans le code ça marche, si dans le header de la classe ou de la fonction tu explique ce qu'elle est censé faire et comment elle interagit avec le reste du code ils sont otut content.
09/08/2006, 21h11
JolyLoic

Pour le point 1, ça peut effectivement arriver. Je suis dans un cas un peu semblable, mais depuis moins longtemps. Mais cette doc sert néanmoins à 2 personnes quoi qu'il arrive :
- Moi, quand j'écris le code, car j'écrit cette doc généralement avant le code, et elle me permet de focaliser et raffiner ma pensée. En gros, elle remplace un peu une phase de specs souvent absente à ce niveau de détails.
- Moi, quand je relis ce code par la suite et que je me demande comment j'ai fait.

Rien que pour ces deux personnes, qui comptent beaucoup pour moi ;) , je trouve que c'est rentable.

Un des gros problèmes de se dire qu'on demandera aux gens, c'est que les gens partent, le code reste. Dans un environnement de travail précédent, la plupart de code était fait par prestations d'entreprises variées suivant les volontés des acheteurs et les phases de la lune, et dans ce contexte, le point 1 n'en était que plus crucial.
10/08/2006, 08h38
mambo

Merci bcp pour tes ces informations, ça était très enrichissant.

Je voulais juste revenir aux méthodologies de commentaires. En fait, par méthodologie, j'entends comment faire pour qu'un commentaire soit lisible par tous le monde, le développeur, le chef de projet, le gas de la maintenance...

Qu'est ce qu'il faut inclure dans le commentaire?auteur?date?...

Est ce qu'il existe des méthodologies de ce genre??
10/08/2006, 13h56
tut

A ma connaissance, il n'y a pas de "méthodologie pour faire des commentaires". Juste des règles de bons sens comme les a énnoncé JolyLoïc. Le problème que tu soulèves relève plus du Génie Logiciel et de la qualité logiciel que du savoir-faire pour commenter le code.
Le développeur, le chef de projet et le gars de la maintenance sont trois personnes différentes qui ont des besoins différents, vis à vis de la documentation de ton logiciel. Tu ne peux a priori pas leur fournir le même document... Pose toi plutôt les bonnes questions : "Je suis le chef de projet, quels sont les renseignements que je cherche ?"
En ce qui me concerne, je rejoins complètement JolyLoïc sur l'ensemble de ses remarques, on sent si je ne m'abuse, une certaine culture de Génie Logiciel derrière... ;) Faire des logiciel sans aucune documentation relève de la non-qualité, et dans des environnements sévères, ça peut être assimilé à une faute professionnelle. Il ne faut pas tomber dans l'excès, mais j'ai trop souvent vu des codeurs-fous passer des mois à faire un truc qui aurait pu être fait en 3-4 semaines, par manque de méthodologie. Faire un logiciel, c'est taper du code à 30 % de son temps, le reste doit servir à rédiger des specifications, faire de la conception, tester, valider, gérer la configuration, etc.... Avec de l'expérience, on s'aperçoit en plus que ça va plus vite, et que la qualité est là. Bref, le métier d'ingénieur-développeur ne se limite pas à la rédaction du code, loin s'en faut.

Enfin concernant les outils type Doxygen, par expérience, je pense que ce type d'outil est très bien adapté à la documentation de bibliothèque, et c'est à peu près tout. Après, pour comprendre du code dans le détails, autant y aller directement, avec un bon éditeur (Source Insight, par exemple, une tuerie ce truc).
Mais quand il s'agit d'utiliser une bibliothèque dont on se cogne des détails d'implémentation, alors là, oui, ce type de doc est très utile. La doc de Qt est pour moi aussi une réference : la doc auto-génerée est très lisible (parce qu'en général les doc générées sont plutôt indigestes : vous avec déja parcouru la doc générée par Rational Rose ? illisible...) et très bien complétée par de la doc "manuelle" sur des points techniques particuliers ou des discours plus généraux.

Bon courage !
11/08/2006, 09h06
dabeuliou

Citation:

Envoyé par JolyLoic

Effectivement. Les développeurs de Qt on fait l'effort de faire le point 1. C'est probablement ce qui fait de la doc de Qt une des meilleures que j'ai lu à ce jour.

Pour ça, ils ont utilisé Doxygen, afin de mèler ce point et le point 3. Ce que je voulais dire, c'est que bien que Doxygen ait pu leur laisser faire le point 1, il n'a assurément pas aidé à le faire. Je pense qu'ils auraient eu plus facile avec un simple traitement de texte ou un wiki.

Euh, tu sous-entendrais pas par là que les développeurs de Qt utilisent Doxygen pour générer leur doc quand même ? Parce que ce n'est pas le cas, c'est même le contraire : je me souviens avoir lu sur le site de Doxygen que Dimitri van Heesch, le concepteur de Doxygen s'est inspiré de la doc de Qt qu'il trouvait agréable et claire pour créer doxygen.
11/08/2006, 09h08
Invité

Citation:

Envoyé par dabeuliou

Dimitri van Heesch, le concepteur de Doxygen s'est inspiré de la doc de Qt qu'il trouvait agréable et claire pour créer doxygen.

C'est exact ;)
12/08/2006, 00h08
JolyLoic

Citation:

Envoyé par dabeuliou

Euh, tu sous-entendrais pas par là que les développeurs de Qt utilisent Doxygen pour générer leur doc quand même ? Parce que ce n'est pas le cas, c'est même le contraire : je me souviens avoir lu sur le site de Doxygen que Dimitri van Heesch, le concepteur de Doxygen s'est inspiré de la doc de Qt qu'il trouvait agréable et claire pour créer doxygen.

En fait, je faisais erreur, tellement le look&feel peut être proche.

Ca n'enlève rien à mon propos, ou j'employais Doxygen comme un raccourci pour désigner un outil extrayant de la doc à partir de commentaires de code et d'analyse de code.