Est-il préférable de documenter les fonctions dans le fichier d'en-tête ou le fichier source?

Dans les langages qui distinguent un fichier "source" et "en-tête" (principalement C et C ++), est-il préférable de documenter les fonctions dans le fichier en-tête:

(dérobé de CCAN )

/**
 * time_now - return the current time
 *
 * Example:
 *  printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
 */
struct timeval time_now(void);

ou dans le fichier source?

(dérobé à PostgreSQL)

/*
 * Convert a UTF-8 character to a Unicode code point.
 * This is a one-character version of pg_utf2wchar_with_len.
 *
 * No error checks here, c must point to a long-enough string.
 */
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...

Notez que certains éléments sont définis dans l'en-tête uniquement, tels que les structures, les macros et les static inlinefonctions. Je parle seulement de choses qui sont déclarées dans un fichier d'en-tête et définies dans un fichier source.

Voici quelques arguments auxquels je peux penser. Je suis enclin à documenter dans le fichier source, mes arguments "Pro-en-tête" peuvent donc être quelque peu faibles.

Pro-header:

• L'utilisateur n'a pas besoin du code source pour voir la documentation.
  • La source peut être difficile, voire impossible, à acquérir.
  • Cela maintient l'interface et la mise en œuvre plus éloignées.

Pro-source:

• Cela rend l'en-tête beaucoup plus court, donnant au lecteur une vue à vol d'oiseau du module dans son ensemble.
• Il associe la documentation d'une fonction à son implémentation, ce qui permet de voir plus facilement qu'une fonction fait ce qu'elle dit.

Lorsque vous répondez, méfiez-vous des arguments basés sur ce que peuvent faire les outils et les "IDE modernes". Exemples:

• En-tête Pro: le pliage de code peut aider à rendre les en-têtes commentés plus navigables en masquant les commentaires.
• Source Pro: cscope de Find this global definitionfonction vous amène au fichier source (où la définition est) plutôt que le fichier d' en- tête (où la déclaration est).

Je ne dis pas qu'il ne faut pas argumenter de la sorte, mais n'oubliez pas que tout le monde n'est pas aussi à l'aise avec les outils que vous utilisez.

Mon avis...

• Expliquez comment utiliser la fonction dans le fichier d'en-tête ou, plus précisément, à proximité de la déclaration.

• Documentez le fonctionnement de la fonction (si cela ne ressort pas du code) dans le fichier source, ou plus précisément, proche de la définition.

Pour la vue d'ensemble dans l'en-tête, vous n'avez pas nécessairement besoin de la documentation qui se ferme: vous pouvez documenter des groupes de déclarations à la fois.

De manière générale, l'appelant devrait s'intéresser aux erreurs et aux exceptions (si seulement elles pouvaient être traduites à mesure qu'elles se propagent à travers les couches d'abstraction) afin que celles-ci soient documentées à proximité des déclarations correspondantes.

Si vous allez utiliser un outil tel que Doxygen (remarquez dans le premier exemple, cela ressemble vraiment à un commentaire Doxygen car il commence par /**), cela n'a pas vraiment d'importance - Doxygen examinera vos fichiers d'en-tête et source et recherchera tous les commentaires pour générer la documentation.

Cependant, je serais plus enclin à mettre les commentaires de documentation dans les en-têtes, où se trouvent les déclarations. Vos clients vont utiliser les en-têtes pour interagir avec votre logiciel. Ils vont inclure ce qu'ils vont inclure dans leurs propres fichiers source et c'est là qu'ils vont d'abord regarder pour voir à quoi ressemble votre API.

Si vous regardez la plupart des bibliothèques Linux, par exemple, votre système de gestion de paquets Linux contient souvent un paquet contenant uniquement les fichiers binaires de la bibliothèque (pour les utilisateurs "normaux" ayant des programmes nécessitant la bibliothèque) et vous avez un paquet "dev" contient les en-têtes de la bibliothèque. Le code source n'est normalement pas fourni directement dans un package. Il serait vraiment fastidieux d’obtenir le code source d’une bibliothèque quelque part pour obtenir la documentation de l’API.

Nous avons résolu ce problème (il y a environ 25 ans) en créant un ensemble de #defines (par exemple, public, private, etc., résolus en <rien>) pouvant être utilisés dans le fichier source et analysés par un script awk (horror !) pour générer automatiquement les fichiers .h. Cela signifie que tous les commentaires résidaient dans la source et ont été copiés (le cas échéant) dans le fichier .h généré. Je sais que c'est assez Old School, mais cela simplifie grandement ce type de documentation en ligne.

En supposant qu'il s'agisse de code dans un projet plus important (où les développeurs vont souvent changer de source et d'en-tête) , et que ce n'est pas une bibliothèque / middleware, où d'autres n'ont peut-être pas accès à la source, j'ai trouvé que cela fonctionnait meilleur...

• En-têtes:
  1-2 commentaires de ligne succincts, uniquement s'ils sont nécessaires.
  Parfois, les commentaires au-dessus d’un groupe de fonctions connexes sont également utiles.
• Source:
  Documentation sur l'API directement au-dessus de la fonction (texte brut ou doxygen si vous préférez) .
• Conservez les détails de l'implémentation, qui ne concernent qu'un développeur qui modifie le code dans le corps de la fonction.

La raison principale en est de garder les commentaires proches du code, j’ai remarqué que les docs dans les en-têtes ont tendance à se désynchroniser plus souvent avec les modifications du code (bien sûr, ils ne devraient pas, mais ils l’ont fait dans notre projet à le moins) . Les développeurs peuvent également ajouter de la documentation au sommet des fonctions lorsqu'ils apportent des modifications, même s'il existe des documents d'en-tête ... quelque part. Causer des doublons ou des informations utiles uniquement dans l'une des chaînes de documentation.

Bien sûr, vous pouvez choisir une convention et vous assurer que tous les développeurs suivent. Je viens de trouver la convention ci-dessus la plus naturelle et la moins dérangeante à maintenir.

Enfin, pour les grands projets - theres une inclinaison non de faire de petites corrections dans un en- tête quand vous savez que sa va potentiellement causer de des fichiers de ou 1000 100 recompiler quand d' autres mettent à jour le contrôle de version - ralentissement des erreurs bissectrice aussi.

À mon avis (plutôt limité et partial), je suis une façon de penser du code source. Lorsque je fais des bricoles en C ++, je modifie généralement le fichier d’en-tête une fois, puis je ne le regarde jamais vraiment.

Lorsque je place la documentation dans le fichier source, je la vois toujours lorsque je modifie ou lis des codes. Je suppose que c'est une chose d'habitude.

Mais c'est juste moi ...

Les commentaires ne sont pas de la documentation. La documentation d'une fonction peut généralement comporter 2 Ko de texte, éventuellement avec des diagrammes - voir, par exemple, la documentation relative aux fonctions dans le SDK de Windows. Même si votre commentaire-à-doc le permet, vous rendrez le code contenant le commentaire illisible. Si vous souhaitez produire de la documentation, utilisez un traitement de texte.

Si les parties prenantes de votre code source (par exemple, une petite bibliothèque) sont composées d '"utilisateurs" (collègues développeurs qui utiliseront les fonctionnalités de votre bibliothèque sans s'impliquer dans son implémentation) et de "développeurs" (vous et d'autres développeurs qui implémenteront la bibliothèque) , placez ensuite les "informations relatives aux utilisateurs" dans l'en-tête et la "note d'implémentation" dans le source.

En ce qui concerne le désir de ne pas modifier les fichiers d’en-tête plus que ce qui est absolument nécessaire - je suppose que si votre bibliothèque n’est pas "dans un flux de changements insensé", l’interface et la "fonctionnalité" ne changeront pas beaucoup, et les commentaires d'en-tête doivent-ils changer trop souvent? D'autre part, les commentaires du code source devront rester synchronisés ("frais") avec le code source.

L’utilisation de doxygen a pour objectif essentiel de générer de la documentation et de la rendre accessible ailleurs. Désormais, toute la documentation contenue dans les en-têtes ne constitue que des déchets, ce qui rend plus difficile la détection rapide de la déclaration de fonction requise, voire de ses surcharges. Un commentaire de ligne est le maximum qui devrait y aller, mais même cela est une mauvaise pratique. Si vous modifiez la documentation dans la source, vous devez recompiler cette source et rétablir le lien. Mais si vous mettez la documentation dans l'en-tête, vous ne voulez vraiment pas changer la moindre chose, car cela va déclencher une partie importante de la reconstruction du projet.