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
Inscrivez-vous gratuitement
pour pouvoir participer, suivre les réponses en temps réel, voter pour les messages, poser vos propres questions et recevoir la newsletter
La doc dans le .c
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!
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).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.
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 !
Mon Site
L'imagination est plus importante que le savoir. A. Einstein
Je ne répond à aucune question technique par MP, merci d'avance !
Moi, lorsque je débutai, un collègue ma dit de les mettres dans les .h, et depuis, j'ai pas changer mes habitudes
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.
Bah oui, bon sens élémentaire... je ne vois pas bien ce qu'il y a à discuter là-dessus...
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
L'imagination est plus importante que le savoir. A. Einstein
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.
+1
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
L'imagination est plus importante que le savoir. A. Einstein
Justement c'est déjà suffisamment le bordel dans les fichiers d'en-tête, il n'est pas nécessaire d'en rajouter.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
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.
Répondre avec citation
Partager