OVH Cloud OVH Cloud

documentation des fichiers sources

16 réponses
Avatar
Olivier Mandavy
Bonjour,

j'ai pour habitude de documenter chacunes de mes méthodes et procédures dans
mes sources, mais est ce nécessaire de documenter le fichier ?
Si oui quelles sont les consignes à suivre ?
Merci.

10 réponses

1 2
Avatar
Fabien SK
On Mon, 17 Nov 2003 19:57:07 +0100, Olivier Mandavy wrote:

j'ai pour habitude de documenter chacunes de mes méthodes et procédures dans
mes sources, mais est ce nécessaire de documenter le fichier ?
Si oui quelles sont les consignes à suivre ?
Merci.


Je documente au format doxygen les classes, méthodes et paramètres.
Normalement, lorsque le lecteur sait ce que doit faire une fonction, il
est déjà sur la bonne voie. Après, je rajoute quelques indications
quand il y a une feinte dans l'algo (des fois c'est nécessaire).
Je dirais qu'il faut commenter de façon à obtenir du code comme on
aimerait le voir quand on doit le maintenir.

Avatar
Loïc Joly
Olivier Mandavy wrote:
Bonjour,

j'ai pour habitude de documenter chacunes de mes méthodes et procédures dans
mes sources, mais est ce nécessaire de documenter le fichier ?


Si tu parles de documenter la philosophie d'utilisation d'un module, en
plus que de documenter (type document de référence) chaque fonction du
module, je trouve que c'est essentiel (à la limite, dans certains cas
simples, les fonctions, je peux encore deviner si les noms sont bien
choisis. La vue globale, j'ai plus de mal.

En général, cette documentation est écrite dans un document à part qui
permet une mise en forme plus évoluée (dessins...) qu'une documntation
dans le code.

--
Loïc

Avatar
Olivier Mandavy
Bonsoir,

oui c'est cela; documenter la philosophie d'utilisation d'un module.
Mais eventuellement ajouter pour chaque module des infos concernant sa date
de création, son auteur, etc...
L'outil de documentation de mon compilo C++ se moque éperduement des
commentaires ajoutés à chaque entête de modules. Aussi je me demandais s'il
était utile de placer ces commentaires ?

"Loïc Joly" wrote in message
news:bpbaad$3ft$
Olivier Mandavy wrote:
Bonjour,

j'ai pour habitude de documenter chacunes de mes méthodes et procédures
dans


mes sources, mais est ce nécessaire de documenter le fichier ?


Si tu parles de documenter la philosophie d'utilisation d'un module, en
plus que de documenter (type document de référence) chaque fonction du
module, je trouve que c'est essentiel (à la limite, dans certains cas
simples, les fonctions, je peux encore deviner si les noms sont bien
choisis. La vue globale, j'ai plus de mal.

En général, cette documentation est écrite dans un document à part qui
permet une mise en forme plus évoluée (dessins...) qu'une documntation
dans le code.

--
Loïc




Avatar
Marc Boyer
Olivier Mandavy wrote:
Bonjour,

j'ai pour habitude de documenter chacunes de mes méthodes et procédures dans
mes sources, mais est ce nécessaire de documenter le fichier ?
Si oui quelles sont les consignes à suivre ?


Une longue discussion a eut lieu sur le sujet ici même,
initiée le 15 septembre par social-traitre avec
comme sujet "les commentaires".
Tu peux la retrouver sur Google à l'URL
http://groups.google.fr/groups?hl=fr&lr=&ie=UTF-8&oe=UTF-8 &threadm=Xns93F97366D976Aisyfur%40127.0.0.1&rnum=1

Marc Boyer
--
Lying for having sex or lying for making war? Trust US presidents :-(

Avatar
kanze
"Olivier Mandavy" wrote in message
news:<bpbb6r$onb$...

oui c'est cela; documenter la philosophie d'utilisation d'un module.
Mais eventuellement ajouter pour chaque module des infos concernant sa
date de création, son auteur, etc...


Ça, je le fais de façon sommaire quand les sources ne sont pas sous un
gestionnaire de sources (SCCS, CVS, Clearcase, etc.). Autrement, c'est
la rôle du gestionnaire de sources de maintenir ce genre d'information.

L'outil de documentation de mon compilo C++ se moque éperduement des
commentaires ajoutés à chaque entête de modules. Aussi je me demandais
s'il était utile de placer ces commentaires ?


Tout dépend de comment tu travailles. Dans la passée, je me servais des
fichiers d'en-tête comme documentation, directement. Dans ce cas-là,
évidemment, c'est utile. Actuellement, je me sers de plus en plus de
doxygen. Là aussi, avec de bons tags, j'arrive à mettre de la
documentation générale de la classe, voire même du groupe de classes, en
tête du fichier d'en-tête, et elle apparaît dans la documentation
générée.

Je ne connais pas d'autres outils. Mais si l'outil n'a pas prévu la
documentation générale de la classe, en plus de la documentation de
chaque fonction membre, je dirais qu'il serait temps de changer d'outil.

--
James Kanze GABI Software mailto:
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

Avatar
Jean-Marc Molina
Je confirme, l'idéal c'est d'utiliser Doxygen pour documenter ton code (au
format JavaDoc en fait).
Tu peux aussi utiliser un serveur CVS pour gérer les différentes versions.
J'utilise Visual SourceSafe depuis des lustres et je pense en changer.

Pour info documenter est aussi simple que ça :

/**
Afficher un texte.

@param texte
Texte à afficher
*/

void afficher_texte (const std:string & texte)
{
...
}

/** indique le début du commentaire
Ensuite vient la description, que fait la fonction ?
Une description des paramètres...
Tu peux même intégrer du HTML à partir d'autres fichiers, c'est vraiment
très puissant ! Jusqu'à insérer des formules mathématiques ! Depuis quelques
versions Doxygen vient avec un wizard qui te permet de gérer la
configuration d'un fichier très rapidement.

JM

--
Clé AntiPourriel : PASUNPOURRIEL (ne pas retirer)
Avatar
kanze
"Jean-Marc Molina" wrote in message
news:<bpcqkm$va0$...

Je confirme, l'idéal c'est d'utiliser Doxygen pour documenter ton code
(au format JavaDoc en fait).


Doxygen peut bien plus que JavaDoc. Une de ses forces, c'est de pouvoir
faire des regroupements : des classes, des fonctions, etc. Se limiter au
format JavaDoc me semble trop contraignant.

Tu peux aussi utiliser un serveur CVS pour gérer les différentes
versions. J'utilise Visual SourceSafe depuis des lustres et je pense
en changer.


Le mieux que je connais, c'est sans doute Clearcase. Les autres dont je
me suis servi, en revanche, n'ont rien apporté de mieux que CVS, alors,
autant rester sur un standard.

Pour info documenter est aussi simple que ça :

/**
Afficher un texte.

@param texte
Texte à afficher
*/

void afficher_texte (const std:string & texte)
{
...
}

/** indique le début du commentaire
Ensuite vient la description, que fait la fonction ?
Une description des paramètres...
Tu peux même intégrer du HTML à partir d'autres fichiers, c'est
vraiment très puissant ! Jusqu'à insérer des formules mathématiques !
Depuis quelques versions Doxygen vient avec un wizard qui te permet de
gérer la configuration d'un fichier très rapidement.


J'ai plutôt à l'utiliser avec des commentaires C++ :

// afficher_text :
// ---------------
//
//! Afficher un texte.
//!
//! param texte
//! Texte à afficher
// -----------------------------------------------------------------------
void afficher_text( std::string const& texte ) ;

Du coup, l'en-tête reste lisible aussi. (C'est important quand tu vas
modifier quelque chose, parce que ce n'est pas la doc générée que tu vas
avoir dans ton éditeur.)

--
James Kanze GABI Software mailto:
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

Avatar
Loïc Joly
Marc Boyer wrote:

Tu peux la retrouver sur Google à l'URL
http://groups.google.fr/groups?hl=fr&lr=&ie=UTF-8&oe=UTF-8
&threadm=Xns93F97366D976Aisyfur%40127.0.0.1&rnum=1


Pour info, www.tinyurl.org peut faciliter le post d'url un peu trop
longues. Par exemple, j'ai créé http://tinyurl.com/vjtn qui pointe au
même endroit.

--
Loïc

Avatar
breholee

Tu peux la retrouver sur Google à l'URL
http://groups.google.fr/groups?hl=fr&lr=&ie=UTF-8&oe=UTF-8
&threadm=Xns93F97366D976Aisyfur%40127.0.0.1&rnum=1


Pour info, www.tinyurl.org peut faciliter le post d'url un peu trop
longues. Par exemple, j'ai créé http://tinyurl.com/vjtn qui pointe au
même endroit.


Mais c'est de l'obfuscation aussi, on ne voit plus où on va. Il y a un
format pour les URL : <URL:http://...>. Avec ça un logiciel de courrier
correct ne massacre pas les URL de plus d'une ligne.


Avatar
Marc Boyer
Benoît Bréholée wrote:
Pour info, www.tinyurl.org peut faciliter le post d'url un peu trop
longues. Par exemple, j'ai créé http://tinyurl.com/vjtn qui pointe au
même endroit.


Mais c'est de l'obfuscation aussi, on ne voit plus où on va. Il y a un
format pour les URL : <URL:http://...>. Avec ça un logiciel de courrier
correct ne massacre pas les URL de plus d'une ligne.


C'est le format officiel Usenet ?

Marc Boyer
--
Lying for having sex or lying for making war? Trust US presidents :-(


1 2