Hello,
J'ai un collegue qui me fait remarquer que visiblement, ecrire dans le .c la doc des fonctions exportées (celles qu'on trouve dans le .h) est entré dans les moeurs..
J'aimerais avoir vos avis
Version imprimable
Hello,
J'ai un collegue qui me fait remarquer que visiblement, ecrire dans le .c la doc des fonctions exportées (celles qu'on trouve dans le .h) est entré dans les moeurs..
J'aimerais avoir vos avis
La place de la doc des fonctions exportées est dans le .h
C'est ce qu'on m'a toujours enseigné en effet..
Mais l'utilisation d'un generateur de doc type doxygen ne change t elle pas la donne quand à la fonction documentatrice du .h?
Les variables et les spécifications des fonctions mises en oeuvre dans un module sont regroupés dans un fichier.h
raison pour laquelle on y accede par la directive #include.
En plus c'est le fichier qui pose le moins de problèmes! :lol: :lol: :lol:
Doxygen gère aussi bien ce qui est dans le .h que dans le .c. Et de plus, il y a une partie de la doc d'utilisation qui n'a sa place ni dans l'un, ni dans l'autre. Doxygen peut servir à la mettre en forme en la prenant ailleurs (dans des .dox par exemple).Citation:
Envoyé par Gruik
Moin on ma toujours dit que la doc des fonctions exportées doit être dans les .h.
Et il ne me semble pas qu'écrire la doc dans les .c soit entré dans les moeurs :?
qu'entendez-vous par doc ???
Moi je dirais :
- dans le .c :
- En tête du fichier : liste des fonctions figurant dans le fichier, classées par scope : local, interne/externe, externe.
- fonction (éventuellement algo) documentée pour le programmeur suivant éventuel dans l'entête de la fonction.
- Commentaires abondants
- Dans le .h :
- Une ligne ou 1/2 ligne de commentaire éventuellement
- Pour la doc :
- Un "man page" soit par fonction soit par module si trop gros.
- Un fichier html de documentation complet.
Citation:
Envoyé par bo turbo
Histoire de garder une certaine unité de mes fichiers sources, je met toujours les mêmes commentaires d'en-tête de mes fonctions aussi bien dans le header que le fichier source. Cependant, s'il s'agit de mettre des commentaires Doxygen pour générer une petite documentation des fonctions, je met uniquement cette version dans le header !
Moi, lorsque je débutai, un collègue ma dit de les mettres dans les .h, et depuis, j'ai pas changer mes habitudes :aie:
Les fichiers d'en-tete etant la partie publique du code, il me semble indispensable qu'ils contiennent la documentation des fonctions (role, valeur de retour, parametre, etc.).
Ensuite rien n'empeche d'avoir les meme commentaires dans les fichiers sources (c'est personellement ce que je fais) meme si ca demande un peu plus de travail pour maintenir cette doc.
Dans tous les cas ca ne dispense pas d'avoir une documentation independantes du code a cote (fichier pdf, html, page man, info, etc.)
Pour ma part je la place dans le .c . Ça me parait plus pratique d'avoir la doc d'une fonction dans le même fichier (ça évite des allers-retours visuels entre 2 fichiers, il suffit de remonter jusqu'en haut de la fonction)
Bien souvent, j'ai pas l'implementation disponible alors que les entetes le sont. Je ne vois donc pas l'interet de mettre la doc d'utilisation a un endroit ou l'utilisateur n'a pas acces.Citation:
Envoyé par muad'dib
Bah oui, bon sens élémentaire... je ne vois pas bien ce qu'il y a à discuter là-dessus...Citation:
Envoyé par Jean-Marc.Bourguet
Ok merci,
Je pense que certains trouvent que c'est plus pratique d'écrire la doc de la fonction en meme temps que le corps de la fonction, donc au dessus d'elle dans le .c... Si la doc est générée systematiquement, ils ne regarderaient plus le .h, ce serait qu'une formalité pour rendre la compilation possible..
Mais je persiste egalement à croire que c'est cracra et on a pas toujours cette doc générée sous la main
Si tu prend le cas de GTK+, eux ils ne mettent aucune description dans les headers et les commentaires pour la génération de la documentation se trouve dans les fichiers sources, m'est d'avis que dans le header, au moins une petite doc ne fait pas de mal ;)
Comment est-ce que tu peux ecrire une fonction publique sans savoir par avance quelle va etre sa doc? Dans ma pratique on concoit d'abord l'interface d'un module, -- ie on ecrit l'entete et la doc d'utilisation. Une fois que tout le monde (y compris les utilisateurs) est d'accord, on implemente.Citation:
Envoyé par Gruik
+1Citation:
Envoyé par Jean-Marc.Bourguet
Par ailleurs lorsque tu comptes implémenter une fonction, c'est que tu l'as déjà conçue ou bien au moins un peu réfléchie alors tu sais ce que tu va écrire ;)
Justement c'est déjà suffisamment le bordel dans les fichiers d'en-tête, il n'est pas nécessaire d'en rajouter.Citation:
Envoyé par Franck.H
En plus si l'implémentation du code n'a pas à être connu, pourquoi celle de la doc le serait ? Il y a les fichiers HTML (ou autre) si tu veux lire la doc.
Bien sûr sans Doxygen & Co ce n'est pas la même chose, il faut forcement mettre la doc dans les fichiers d'en-tête.
Un bon compromis serait de mettre la doc dans les fichiers d'entêtes uniquement pour les fonctions publiques, pour expliquer comment les utiliser aux utilisateurs. La doc de l'implémentation quant à elle pourrait être constituée de la doc du .h complétée d'une documentation destinée aux autres programmeurs.Citation:
Envoyé par gege2061
+2Citation:
Envoyé par Jean-Marc.Bourguet
Bah, de toutes façons, dans les entêtes publiques, par définition, il n'y a des prototypes que de fonctions publiques... Je ne ne comprends pas l'objet de cette discussion. Il suffit d'un peu de bon sens et on se rend compte qu'elle n'a pas lieu d'être...Citation:
Envoyé par muad'dib
A lire d'urgence :
http://emmanuel-delahaye.developpez.com/codage.htm
C'est pas moi qui faut engueuler :aie:Citation:
Envoyé par Jean-Marc.Bourguet
Je savais ça, j'y ai pas pensé quand j'ai posté
+10Citation:
Envoyé par Emmanuel Delahaye
Je ne comprends vraiment pas où on vous a appris ou dit qu'il fallait mettre la doc dans les .h ...
Ayant très fortement l'habitude des OS unixoides, mais aussi de VMS, la doc est TOUJOURS à part... (man pages, et éventuellement un .html avec) et dans le .c, mais certainment pas dans le .h.
Ce que j'ai le plus appris avec les OS unixoïdes, c'est "No manual entry for [la-fonction-que-je-cherche]".
C'est pourquoi je trouve que c'est pas mal d'avoir la liste des fonctions publiques et leur aide directement dans les headers...
man -k ???Citation:
Envoyé par Médinoc