Bonjour tlm,
Est ce que quelqu'un saurait s'il existe des méthodologies de commentaires du code?
Merci.
Bonjour tlm,
Est ce que quelqu'un saurait s'il existe des méthodologies de commentaires du code?
Merci.
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
Plus y'a d'Gruyère, plus y'a d'trous !
Plus y'a d'trous, moins y'a d'Gruyère...
Donc, Plus y'a d'Gruyère, moins y'a d'Gruyère !!!
Tu pourrais me dire un peu plus sur d'oxygen?
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
Plus y'a d'Gruyère, plus y'a d'trous !
Plus y'a d'trous, moins y'a d'Gruyère...
Donc, Plus y'a d'Gruyère, moins y'a d'Gruyère !!!
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...Envoyé par mambo
besoin de réponses ? demande a un pote
Merci bcp à tous les deux je vais m'y mettre.
Tu trouveras un tuto là :
http://cyberzoide.developpez.com/java/doxygen/
D'accord, c'est pour java, mais pour commenter, ça change pas beaucoup
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):
Peut se remplacer par :
Code : Sélectionner tout - Visualiser dans une fenêtre à part
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; }
0 commentaires, mais code mieux commenté !
Code : Sélectionner tout - Visualiser dans une fenêtre à part
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(); }
(**) 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...
Ma session aux Microsoft TechDays 2013 : Développer en natif avec C++11.
Celle des Microsoft TechDays 2014 : Bonnes pratiques pour apprivoiser le C++11 avec Visual C++
Et celle des Microsoft TechDays 2015 : Visual C++ 2015 : voyage à la découverte d'un nouveau monde
Je donne des formations au C++ en entreprise, n'hésitez pas à me contacter.
Salut,
J'ai dû rater un truc, mais il me semble que c'est exactement la remarque que tu fait pour Doxygen:Envoyé par JolyLoic
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...Envoyé par JolyLoic
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...).
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
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.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...).
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 !
Plus y'a d'Gruyère, plus y'a d'trous !
Plus y'a d'trous, moins y'a d'Gruyère...
Donc, Plus y'a d'Gruyère, moins y'a d'Gruyère !!!
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.Envoyé par plegat
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.
Ma session aux Microsoft TechDays 2013 : Développer en natif avec C++11.
Celle des Microsoft TechDays 2014 : Bonnes pratiques pour apprivoiser le C++11 avec Visual C++
Et celle des Microsoft TechDays 2015 : Visual C++ 2015 : voyage à la découverte d'un nouveau monde
Je donne des formations au C++ en entreprise, n'hésitez pas à me contacter.
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.Envoyé par JolyLoic
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.
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.
Ma session aux Microsoft TechDays 2013 : Développer en natif avec C++11.
Celle des Microsoft TechDays 2014 : Bonnes pratiques pour apprivoiser le C++11 avec Visual C++
Et celle des Microsoft TechDays 2015 : Visual C++ 2015 : voyage à la découverte d'un nouveau monde
Je donne des formations au C++ en entreprise, n'hésitez pas à me contacter.
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??
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 !
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.Envoyé par JolyLoic
C'est exactEnvoyé par dabeuliou
besoin de réponses ? demande a un pote
En fait, je faisais erreur, tellement le look&feel peut être proche.Envoyé par dabeuliou
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.
Ma session aux Microsoft TechDays 2013 : Développer en natif avec C++11.
Celle des Microsoft TechDays 2014 : Bonnes pratiques pour apprivoiser le C++11 avec Visual C++
Et celle des Microsoft TechDays 2015 : Visual C++ 2015 : voyage à la découverte d'un nouveau monde
Je donne des formations au C++ en entreprise, n'hésitez pas à me contacter.
Vous avez un bloqueur de publicités installé.
Le Club Developpez.com n'affiche que des publicités IT, discrètes et non intrusives.
Afin que nous puissions continuer à vous fournir gratuitement du contenu de qualité, merci de nous soutenir en désactivant votre bloqueur de publicités sur Developpez.com.
Partager