Où documenter les fonctions en C? [fermé]

vous devez utiliser un outil comme doxygen , de sorte que la documentation est générée par des commentaires spécialement conçus dans votre code source.

j'aime suivre le guide de style de Google c++ .

qui dit:

Déclarations De Fonction

• toute déclaration de fonction doit avez des commentaires précédant immédiatement ce qui décrivent ce que la fonction et comment l'utiliser. Ils les commentaires doivent être descriptifs ("Ouvrir le fichier") plutôt que de impératif ("Ouvrir le fichier"); la commentaire décrit l' la fonction, il ne dit pas à la fonction quoi faire faire. En général, ces commentaires ne décrire le fonctionnement de la fonction sa tâche. Au lieu de cela, cela devrait être laissé aux commentaires dans la fonction définition.

Définition De La Fonction

• chaque définition de fonction devrait avoir un commentaire décrivant ce que la fonction et tout ce qui est délicat à propos de la façon dont il fait son travail. Pour exemple, dans le définition commentaire vous pourriez décrire tous les trucs de codage vous utilisez, donner un aperçu de l' les étapes que vous traversez, ou expliquer pourquoi vous avez choisi d'implémenter la fonction de la façon dont vous avez fait plutôt que d'utiliser une alternative viable. Par exemple, vous pourriez mentionner pourquoi il doit acquérir une serrure pour la première moitié de la la fonction mais pourquoi il n'est pas nécessaire pour la seconde moitié.

  Note vous ne devez pas simplement répéter le commentaires donnée avec la fonction la déclaration, dans le .h fichier ou où. Il est normal de récapituler brièvement en quoi la fonction, mais l'objet des commentaires devrait être sur la façon dont il le fait.

j'ai fait des allers - retours sur ceci et finalement j'ai réglé sur la documentation dans les fichiers d'en-tête. Pour la grande majorité des API en C / C++, vous avez accès au fichier d'en-tête original et donc à tous les commentaires qui se trouvent dans [1]. Mettre des commentaires ici maximise les chances des développeurs de les voir.

cependant, j'évite la duplication des commentaires entre les fichiers d'en-tête et les fichiers source (cela ressemble à un gaspillage). C'est vraiment ennuyeux quand on utilise Vim, mais la plupart des IDEs le feront. récupérez les commentaires du fichier d'en-tête et mettez-les dans des choses comme intellisense ou l'aide de paramètre.

[1] Les Exceptions à cette règle incluent les fichiers d'en-tête générés à partir de certaines bibliothèques COM.

Il dépendra souvent de ce qui est défini comme la norme de codage. Beaucoup de gens préfèrent mettre la documentation dans le .h fichier et laisser la mise en œuvre dans le .c fichier. Beaucoup D'IDE avec l'achèvement de code vont également ramasser plus facilement sur ce plutôt que la documentation dans le .c fichier.

Mais je pense que le point important dans la réalisation de la documentation dans le .h file traite de l'écriture d'une bibliothèque ou d'un assemblage qui sera partagé avec un autre programme. Imaginez que vous êtes l'écriture d'un .dll (ou .donc) qui contient un composant que vous distribuerez. D'autres programmeurs incluront votre .h, mais ils n'ont souvent pas (ni besoin) du fichier de mise en œuvre. Dans ce cas, la documentation dans le .le dossier h est inestimable.

on peut dire la même chose quand on écrit une classe pour l'utiliser dans le même programme. Si vous travaillez avec d'autres programmeurs, le plus souvent les programmeurs sont simplement en regardant le fichier d'en-tête pour la façon d'interagir avec votre code plutôt que la façon dont le code est mis en œuvre. La façon dont il est mis en œuvre n'est pas la préoccupation de la personne ou du code qui utilisera le composant. Donc, encore une fois, de la documentation dans l'en-tête aidera cette personne ou ces personnes à comprendre comment utiliser ce code.

vous pouvez simplement utiliser Doxygen .. Aussi, vous pouvez regarder cette réponse .

considèrent qu'il est possible pour les gens d'utiliser ces fonctions tout en ayant seulement les en-têtes et une version compilée de l'implémentation. Assurez-vous que tout ce qui est nécessaire à l'utilisation de vos fonctions est documenté dans l'en-tête. Les détails de la mise en œuvre peuvent être documentés dans la source.

certainement garder les docs dans un endroit, pour éviter le cauchemar d'entretien. Vous, personnellement, êtes assez méticuleux pour garder deux copies synchronisées, mais la prochaine personne ne le fera pas.

utilisez quelque chose comme Doxygen pour créer une" jolie " version des docs.

c'est très simple quand on y pense.

les docs API doivent absolument aller dans le fichier d'en-tête. C'est le fichier d'en-tête qui définit l'interface externe, donc c'est là que vont les docs de L'API.

en règle générale, les détails de la mise en œuvre doivent être cachés aux utilisateurs de L'API. Cela inclut la documentation de la mise en œuvre (sauf dans les cas où cela pourrait affecter l'utilisation, par exemple la complexité temporelle, etc.). La documentation relative à la mise en œuvre devrait donc être insérée dans le rapport. la mise en œuvre de fichier.

ne dupliquez jamais la documentation en plusieurs endroits. Il sera impossible de le maintenir et sera désynchronisé dès que quelqu'un devra le changer.

j'ai écrit un script simple qui prend comme entrée un en-tête de modèle-fichier sans déclarations de fonction et un fichier de code source avec des fonctions commentées. Le script extrait le commentaire avant une définition de fonction à partir du fichier de code source et l'écrit ainsi que la déclaration de fonction associée dans un en-tête de sortie-fichier. Cela garantit que 1) Il n'y a qu'un seul endroit où le commentaire de la fonction doit être écrit; et 2) la documentation dans le fichier d'en-tête et le fichier de code source toujours rester en synchronisation. Commentaire sur la mise en œuvre d'une fonction est placé dans le corps de la fonction et n'est pas extrait.

les commentaires dans l'en-tête par rapport au fichier de mise en œuvre doivent refléter la différence dans la façon dont les deux sont utilisés.

si vous allez créer de la documentation d'interface (par exemple, à extraire avec Doxygen, dans le même ordre général que JavaDocs) qui appartient clairement à l'en-tête. Même si vous n'allez pas extraire les commentaires pour produire une documentation séparée, la même idée générale s'applique -- les commentaires qui expliquent l'interface/comment utiliser le code, appartiennent principalement ou exclusivement dans l'en-tête.

les commentaires dans la mise en œuvre devraient généralement se rapporter à la mise en œuvre. Contrairement à la pratique courante, plutôt que d'essayer d'expliquer comment les choses fonctionnent, la plupart devrait expliquer pourquoi les décisions particulières ont été prises. Cela est particulièrement vrai quand vous prenez des décisions qui ont du sens, mais il pourrait ne pas être évident qu'ils le font (par exemple, en notant que vous avez fait pas utilisez un Quicksort, parce que vous avez besoin d'une sorte stable).