Où documenter les fonctions en C?

Question

J'ai un programme C avec plusieurs fichiers, j'ai donc, par exemple, stuff.c qui implémente quelques fonctions, et stuff.h avec les prototypes de fonction.

Comment dois-je aller sur la documentation des fonctions dans les commentaires?

Si j'ai tous les docs dans le fichier d'en-tête, tous les docs en .c le fichier, ou de dupliquer les docs pour les deux? J'aime la dernière approche, mais ensuite, j'ai couru dans des problèmes où je vais mettre à jour la documentation sur l'un d'eux et pas les autres (généralement celle où je fais la première modification, c'est à dire si je modifie le fichier d'en-tête d'abord, puis ses commentaires seront le reflet, mais si je l'ai mise à jour de la mise en œuvre, seuls les commentaires de changement).

Answer 1

• Mettez les informations que les personnes utilisant les fonctions doivent connaître dans l'en-tête.

• Mettez les informations que les responsables des fonctions doivent connaître dans le code source.

Answer 2

J'aime suivre le Google C++ Guide de Style.

Qui dit:

Les Déclarations De Fonction

• Chaque 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. Ces les commentaires doivent être descriptifs ("Ouvrir le fichier") plutôt que de impératif ("Ouvrir le fichier"); la commentaire décrit la fonction, il ne pas dire à la fonction de quoi n'. En général, ces commentaires ne décrire la façon dont la fonction s'exécute sa tâche. Au lieu de cela, qui devrait être de gauche à des commentaires dans la fonction définition.

Définitions De Fonction

• Chaque définition de fonction doit avoir un commentaire décrivant ce que la la fonction ne et rien de difficile à propos de la façon dont il fait son travail. Pour exemple, dans la définition de commentaire vous pourriez décrire toutes les astuces de codage vous utilisez, donner un aperçu de l' étapes vous allez à travers, ou d'expliquer pourquoi vous avez choisi de mettre en œuvre la fonction dans la façon dont vous l'avez fait, plutôt que d'utiliser une alternative viable. Par exemple, vous pourriez mentionner les raisons pour lesquelles elle doit acquérir un verrou pour le premier semestre de l' la fonction mais pourquoi il n'est pas nécessaire pour la seconde moitié.

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

Answer 3

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.

Answer 4

Je suis allé en arrière et en avant sur ce sujet et finalement je me suis rabattue sur de la documentation dans les fichiers d'en-tête. Pour la grande majorité des Api en C/C++, vous avez accès à l'original du fichier d'en-tête et donc tous les commentaires qui se trouvent dans [1]. Mettre des commentaires ici maximise la possibilité aux développeurs de les voir.

- Je éviter la duplication des commentaires entre en-tête et les fichiers source (il se sent juste comme un déchet). C'est vraiment gênant lors de l'utilisation de Vim, mais la plupart des IDEs va chercher le fichier d'en-tête de commentaires et de les mettre dans des choses comme intellisense ou de l'aide sur les paramètres.

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

Answer 5

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

Mais je pense que le point important dans la réalisation de la documentation dans le .h dossier traite avec l'écriture d'une bibliothèque ou d'un assemblage qui peut être partagé avec un autre programme. Imaginez que vous êtes en train de rédiger un .dll (ou .donc) qui contient un composant qui vous seront distribués. D'autres programmeurs vont inclure votre .h, mais souvent, ils n'auront pas (ni) la mise en œuvre de fichier derrière elle. Dans ce cas, la documentation dans le .h fichier est inestimable.

La même chose peut être dit quand vous écrivez une classe pour l'utilisation 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 sera en utilisant 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.