C++Talk.NET C++ language newsgroups   Archives   FAQ   Search   Memberlist   Usergroups   Register   Profile   Log in to check your private messages   Log in  Re: les commentaires Goto page 1, 2, 3  Next          C++Talk.NET Forum Index -> C++ (French) View previous topic :: View next topic   Author Message Loïc Joly Guest Posted: Mon Sep 15, 2003 6:58 pm    Post subject: Re: les commentaires drkm wrote: Quote: "social-traitre" <social-traitre (AT) wanadoo (DOT) fr.invalid> writes: Ma question, qui s'addresse principalement à ceux qui mettent des commentaires Il existe des développeurs qui n'utilisent pas de commentaires ? Pour ce qui est de la question, je pense que la réponse est assez directe : ce qui a trait à la documentation « publique » dans l'entête, ce qui a trait à l'implémentation, dans les fichiers sources. J'y mettrait un bémol : S'il y a trop de documentation, particulièrement dans un en-tête, je trouve que l'on a du mal à avoir une vue globale de la classe. C'est pourquoi je préfère mettre la documentation publique détaillée dans un autre document, et ne mettre dans le .h que les points de détails qui se disent vite. -- Loïc Back to top drkm Guest Posted: Mon Sep 15, 2003 9:00 pm    Post subject: Re: les commentaires "social-traitre" <social-traitre (AT) wanadoo (DOT) fr.invalid> writes: Quote: Ma question, qui s'addresse principalement à ceux qui mettent des commentaires Il existe des développeurs qui n'utilisent pas de commentaires ? Pour ce qui est de la question, je pense que la réponse est assez directe : ce qui a trait à la documentation « publique » dans l'entête, ce qui a trait à l'implémentation, dans les fichiers sources. Le plus dur étant bien sûr de faire la part des choses entre ce qui est publique et ce qui est destiné à ceux qui lisent les fichiers d'implémentation. --drkm Back to top social-traitre Guest Posted: Tue Sep 16, 2003 5:28 am    Post subject: Re: les commentaires "Loïc Joly" <loic.actarus.joly (AT) wanadoo (DOT) fr> a écrit dans le message de news:bk59di$h3h$1 (AT) news-reader1 (DOT) wanadoo.fr... Quote: J'y mettrait un bémol : S'il y a trop de documentation, particulièrement dans un en-tête, je trouve que l'on a du mal à avoir une vue globale de la classe. C'est pourquoi je préfère mettre la documentation publique détaillée dans un autre document, et ne mettre dans le .h que les points de détails qui se disent vite. Sauf que dans ce cas, le remède me semble pire que le mal, puisqu'il implique une redondance de l'information, que je qualifiais de funeste dans mon premier courrier. Bien sûr, mettre la description complète de l'interface dans l'entête rend le tout plus volumineux, et sans doute moins agréable pour celui qui va lire l'entête pour rapidement obtenir une "vue globale de la classe", mais à cela on peut répondre deux choses: la première c'est que pour la vue globale il faut justement aller voir la documentation générée (disons que c'est un peu l'intérêt), et la deuxième c'est que tout le monde est amené à faire du refactoring, même léger, mais tout bête comme de rajouter un paramètre, ou de modifier un comportement non-nominal. Et dans ce cas, avoir deux documents à modifier augmente considérablement le risque d'erreur et de non-synchronization entre le code et la documentation. Déjà qu'avec un seul fichier, c'est loin d'être rare. Back to top social-traitre Guest Posted: Tue Sep 16, 2003 5:33 am    Post subject: Re: les commentaires "drkm" <darkman_spam (AT) yahoo (DOT) fr> a écrit dans le message de news:wk65jtsr6j.fsf (AT) yahoo (DOT) fr... Quote: Ma question, qui s'addresse principalement à ceux qui mettent des commentaires Il existe des développeurs qui n'utilisent pas de commentaires ? Si vous en doutez, c'est sans doute que vous n'appartenez pas à notre civilisation, ou que vous avez été artificiellement maintenu à l'écart de l'humanité pendant la plus grande partie de votre vie. En tout cas, bienvenue parmi nous, Darkman !! La réponse est oui, il y a des développeurs, qui ne mettent pas de commentaires. Plein. Partout. Ils sont là. Parmi nous. Votre femme, votre meilleur ami, votre chef en sont peut-être. Back to top Loïc Joly Guest Posted: Tue Sep 16, 2003 6:21 am    Post subject: Re: les commentaires social-traitre wrote: Quote: Bien sûr, mettre la description complète de l'interface dans l'entête rend le tout plus volumineux, et sans doute moins agréable pour celui qui va lire l'entête pour rapidement obtenir une "vue globale de la classe", mais à cela on peut répondre deux choses: la première c'est que pour la vue globale il faut justement aller voir la documentation générée (disons que c'est un peu l'intérêt), et la deuxième c'est que tout le monde est amené à faire du refactoring, même léger, mais tout bête comme de rajouter un paramètre, ou de modifier un comportement non-nominal. Et dans ce cas, avoir deux documents à modifier augmente considérablement le risque d'erreur et de non-synchronization entre le code et la documentation. Déjà qu'avec un seul fichier, c'est loin d'être rare. Donc, tu préfères devoir gérer deux documents (dont est est de lecture malaisée) à chaque fois que tu lis le code, plutôt que de devoir gérer deux documents à chaque fois que tu le modifies ? -- Loïc Back to top social-traitre Guest Posted: Tue Sep 16, 2003 6:42 am    Post subject: Re: les commentaires "Loïc Joly" <loic.actarus.joly (AT) wanadoo (DOT) fr> a écrit dans le message de news:bk6a2u$cr1$1 (AT) news-reader4 (DOT) wanadoo.fr... Quote: Donc, tu préfères devoir gérer deux documents (dont est est de lecture malaisée) à chaque fois que tu lis le code, plutôt que de devoir gérer deux documents à chaque fois que tu le modifies ? En fait, ça dépend de l'utilisation. Pour lire la documentation de l'interface, afin d'utiliser la classe en question par ailleurs, je ne veux avoir affaire ni au .h ni au .cpp, mais à la documentation générée (par doxygen, par exemple). Lorsqu'il s'agit de modifier le code, je préfèrerais justement n'avoir qu'un seul document en tout et pour tout à maintenir, un peu comme ce qui se fait en java, car je trouve ça assez pratique. Après quitte à en avoir deux, j'aimerais autant m'éviter un troisième qui serait la documentation externe. De toute façon, dans les cas pratiques les plus courants, j'aurai toujours deux documents à maintenir: l'entête et l'implémentation, et c'est principalement ce qui m'ennuie. Finalement je vais faire comme (presque) tout le monde, mettre ma grosse doc dans les entêtes, et presque rien dans les .cpp. Mais c'est quand même dommage, et je reste sur la sensation que la "bonne" solution (celle sans inconvénient par ailleurs) n'existe pas. Back to top Fabien SK Guest Posted: Tue Sep 16, 2003 7:14 am    Post subject: Re: les commentaires drkm wrote: Quote: Ma question, qui s'addresse principalement à ceux qui mettent des commentaires Il existe des développeurs qui n'utilisent pas de commentaires ? Si je mettais des commentaires (et des noms de variables et classes compréhensibles), mon patron pourrait se débarasser facilement de moi :-) Back to top Mickael Pointier Guest Posted: Tue Sep 16, 2003 7:51 am    Post subject: Re: les commentaires Quote: Donc, tu préfères devoir gérer deux documents (dont est est de lecture malaisée) à chaque fois que tu lis le code, plutôt que de devoir gérer deux documents à chaque fois que tu le modifies ? En fait, ça dépend de l'utilisation. Pour lire la documentation de l'interface, afin d'utiliser la classe en question par ailleurs, je ne veux avoir affaire ni au .h ni au .cpp, mais à la documentation générée (par doxygen, par exemple). Ce que je fait aussi. Ca implique que la "doxygénation" soit faite régulièrement histoire que la doc reste à jour. Et je la repousse sous Source Safe avec le reste du code après. Quote: Lorsqu'il s'agit de modifier le code, je préfèrerais justement n'avoir qu'un seul document en tout et pour tout à maintenir, un peu comme ce qui se fait en java, car je trouve ça assez pratique. Après quitte à en avoir deux, j'aimerais autant m'éviter un troisième qui serait la documentation externe. De toute façon, dans les cas pratiques les plus courants, j'aurai toujours deux documents à maintenir: l'entête et l'implémentation, et c'est principalement ce qui m'ennuie. Finalement je vais faire comme (presque) tout le monde, mettre ma grosse doc dans les entêtes, et presque rien dans les .cpp. Mais c'est quand même dommage, et je reste sur la sensation que la "bonne" solution (celle sans inconvénient par ailleurs) n'existe pas. Je ne commente que l'implémentation. Si c'est une méthode inline, ca sera évidement dans le .h Mike Back to top drkm Guest Posted: Tue Sep 16, 2003 7:52 am    Post subject: Re: les commentaires "social-traitre" <social-traitre (AT) wanadoo (DOT) fr.invalid> writes: Quote: "drkm" <darkman_spam (AT) yahoo (DOT) fr> a écrit dans le message de news:wk65jtsr6j.fsf (AT) yahoo (DOT) fr... Il existe des développeurs qui n'utilisent pas de commentaires ? Si vous en doutez, c'est sans doute que vous n'appartenez pas à notre civilisation, ou que vous avez été artificiellement maintenu à l'écart de l'humanité pendant la plus grande partie de votre vie. Si tu parles de l'humanité qui ne connaît que l'informatique et ne sait parler que de son pécé, qui en plus n'utilise pas de commentaire dans son code source, alors oui, c'est possible. Quote: La réponse est oui, il y a des développeurs, qui ne mettent pas de commentaires. Plein. Partout. Ils sont là. Parmi nous. Votre femme, votre meilleur ami, votre chef en sont peut-être. Et ils ont le petit doigt tout raide et parlent avec un fort accent ? --drkm Back to top Mickael Pointier Guest Posted: Tue Sep 16, 2003 1:25 pm    Post subject: Re: les commentaires Quote: Comme beaucoup ici, je déclare mes classes dans des .h, et j'écris l'implémentation dans des .cpp. De plus, j'aimerais associer à chaque méthode un commentaire, identique à ce qui se fait en Java avec la JavaDoc: décrire le comportement de la méthode, les arguments attendus, bref le contrat général de la méthode. Ben, Doxygen permet de faire de choses tout comme JavaDoc. C'est vrai qu'une utilisation d'outil de documentation automatique (un peu verbeux quand même) pour ma part tend à remplacer la lecture du fichier d'entête (.h ou .hpp) par la navigation dans la doc. Les commentaires sur l'implémentation sont, dans mon usage, uniquement dans le code, en format texte brut. Si l'ensemble est un peu touffu, une doc externe (LaTeX, texte...) vient présenter les choix généraux, les pièges, etc. J'intègre ca dans la doc doxygene. Dans tous mes projets j'ai un fichier "documentation.cpp" qui ne contient en fait que des commentaires doxygen décrivant des sections qui apparaitrons sous forme de pages séparées dans la doc finale. Dedans je fait référence aux structures et fonctions présentes dans l'API, et de même je met des exemples de code utilisateur qui deviennent "clickables" renvoyant immédiatement sur la documentation de l'élément clické. Du doxygene pur sans information d'utilisation additionnelle ne me parait guère plus intéressant qu'un fichier header. Mike Back to top Marc Boyer Guest Posted: Tue Sep 16, 2003 1:31 pm    Post subject: Re: les commentaires Mickael Pointier wrote: Quote: Les commentaires sur l'implémentation sont, dans mon usage, uniquement dans le code, en format texte brut. Si l'ensemble est un peu touffu, une doc externe (LaTeX, texte...) vient présenter les choix généraux, les pièges, etc. J'intègre ca dans la doc doxygene. Dans tous mes projets j'ai un fichier "documentation.cpp" qui ne contient en fait que des commentaires doxygen décrivant des sections qui apparaitrons sous forme de pages séparées dans la doc finale. Dedans je fait référence aux structures et fonctions présentes dans l'API, et de même je met des exemples de code utilisateur qui deviennent "clickables" renvoyant immédiatement sur la documentation de l'élément clické. Je suis pas encore assez à l'aise avec Doxygen pour ça. J'aime bien mes sections, sous-sections et notes de bas de page. Et puis j'en reste à la distinction entre la doc qu'on imprime et la doc sur laquelle on navigue. Je changerai peut-être de point de vue un jour. Quote: Du doxygene pur sans information d'utilisation additionnelle ne me parait guère plus intéressant qu'un fichier header. Ben, ça évite d'avoir à générer le fichier de tags, et on peut la mettre sur le WEB. Ca engendre la hiérarchie de classes aussi. Et puis ça permet aux gens qui aimait pas documenter leur code de prétendre qu'ils l'ont fait parce qu'il on mis plein de @param partout ;-) Marc Boyer -- Lying for having sex or lying for making war? Trust US presidents :-( Back to top kanze@gabi-soft.fr Guest Posted: Tue Sep 16, 2003 4:57 pm    Post subject: Re: les commentaires Fabien SK <fabsk+news (AT) free (DOT) fr> wrote Quote: drkm wrote: Ma question, qui s'addresse principalement à ceux qui mettent des commentaires Il existe des développeurs qui n'utilisent pas de commentaires ? Si je mettais des commentaires (et des noms de variables et classes compréhensibles), mon patron pourrait se débarasser facilement de moi Si j'écris du code incompréhensible, le patron ne peut plus se passer de moi. C'est la sécurité de l'emploi. Au moins pour la durée de vie du projet ; par la suite, ça se sait, et je ne trouve l'emploi nulle part. Si j'apporte des nouvelles idées, des solutions originales, et qu'en plus, j'augmente la productivité des collègues, le patron ne VEUT pas se passer de moi ; surtout, il aurait hâte de m'utiliser sur des nouveaux projets (en général plus intéressant que la maintenance). Et je trouverai toujours l'emploi, même dans vingt ans. Ça, c'est la théorie, au moins. Si je régarde ma carrière, ça a marché aussi assez bien dans la pratique. Pour moi, en tout cas -- YMMV, comme on écrit aux ÉU. -- James Kanze GABI Software mailto:kanze (AT) gabi-soft (DOT) fr Conseils en informatique orientée objet/ http://www.gabi-soft.fr Beratung in objektorientierter Datenverarbeitung 11 rue de Rambouillet, 78460 Chevreuse, France, +33 (0)1 30 23 45 16 Back to top Gabriel Dos Reis Guest Posted: Tue Sep 16, 2003 6:42 pm    Post subject: Re: les commentaires drkm <darkman_spam (AT) yahoo (DOT) fr> writes: Quote: kanze (AT) gabi-soft (DOT) fr writes: YMMV, comme on écrit aux ÉU. ? Your Mileage May Vary. -- Gaby Back to top social-traitre Guest Posted: Tue Sep 16, 2003 6:55 pm    Post subject: Re: les commentaires "Mickael Pointier" <mpointie (AT) eden-studios (DOT) fr> a écrit dans le message de news:bk6e9u$njg$1 (AT) reader1 (DOT) imaginet.fr... Quote: Je ne commente que l'implémentation. Si c'est une méthode inline, ca sera évidement dans le .h Là, ça m'étonne. Je pars du principe que j'écris du code utilisable par d'autres, et qu'on peut l'utiliser comme une bibliothèque déjà compilée (à condition que le compilateur soit le même, cela va de soi). Dans ce cas, ce qui est le plus pratique à utiliser pour mes camarades, ce sont juste les entêtes et le gros .lib. Bien sûr, je donne aussi la documentation doxygénée, mais si jamais elle n'est pas présente, j'aime autant que le développeur lise un fichier d'entête avec tous les commentaires pertinents de la classe. Dans le cas où les commentaires sont dans l'implémentation, la documentation doxygénée devient totalement indispensable, puisqu'il n'y a plus rien dans les entêtes que la signature des classes. Juste ? Si oui, quels sont les avantages de mettre la documentation dans l'implémentation plutôt que dans les entêtes ? Back to top Fabien SK Guest Posted: Wed Sep 17, 2003 6:47 am    Post subject: Re: les commentaires Quote: Si je mettais des commentaires (et des noms de variables et classes compréhensibles), mon patron pourrait se débarasser facilement de moi :-) Si j'écris du code incompréhensible, le patron ne peut plus se passer de moi. C'est la sécurité de l'emploi. Au moins pour la durée de vie du projet ; par la suite, ça se sait, et je ne trouve l'emploi nulle part. C'était de l'humour bien entendu :-) Back to top Display posts from previous: All Posts1 Day7 Days2 Weeks1 Month3 Months6 Months1 Year Oldest FirstNewest First         C++Talk.NET Forum Index -> C++ (French) All times are GMT Goto page 1, 2, 3  Next Page 1 of 3   Jump to: Select a forum C/C++----------------C LanguageC Language (Moderated)C++ Language (Moderated)C++ language (comp.lang.c++)C++ language, library and standards Non-English C/C++ Newsgroups----------------C++ (German)C++ (French)  You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum Powered by phpBB © 2001, 2006 phpBB Group SEO toolkit © 2004-2006 webmedic.