web-dev-qa-db-fra.com

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 d'en-tête:

(chapardé 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?

(chapardé à partir de 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 certaines choses sont définies dans l'en-tête uniquement, telles que les structures, les macros et static inline les fonctions. Je ne parle que des 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 penche vers la documentation dans le fichier source, donc mes arguments "Pro-header" peuvent être quelque peu faibles.

En-tête pro:

  • L'utilisateur n'a pas besoin du code source pour voir la documentation.
    • La source peut être gênante, voire impossible, à acquérir.
    • Cela garde l'interface et l'implémentation plus éloignées.

Pro-source:

  • Cela rend l'en-tête beaucoup plus court, offrant 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, veuillez vous méfier des arguments basés sur ce que les outils et les "IDE modernes" peuvent faire. Exemples:

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

Je ne dis pas de ne pas faire de tels arguments, mais gardez à l'esprit que tout le monde n'est pas aussi à l'aise avec les outils que vous utilisez.

c++cheaders
94
Joey Adams

Mon avis...

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

  • Documentez le fonctionnement de la fonction (si ce n'est pas évident d'après le code) dans le fichier source, ou plus précisément, près de la définition.

Pour ce qui est à vol d'oiseau 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.

D'une manière générale, l'appelant doit être intéressé par les erreurs et les exceptions (ne serait-ce que pour qu'elles puissent être traduites au fur et à mesure qu'elles se propagent à travers les couches d'abstraction), de sorte que celles-ci doivent être documentées à proximité des déclarations pertinentes.

101
Steve314

Si vous allez utiliser un outil tel que Doxygen (remarquez dans le premier exemple, cela ressemble vraiment à un commentaire Doxygen car il commence par /**) alors cela n'a pas vraiment d'importance - Doxygen va parcourir votre en-tête et vos fichiers source et trouver 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 gérer les en-têtes pour s'interfacer avec votre logiciel, les en-têtes sont ce qu'ils incluront dans leurs propres fichiers source et c'est là qu'ils chercheront en premier 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 a souvent un paquet qui ne contient que les binaires de la bibliothèque (pour les utilisateurs "normaux" qui ont des programmes qui ont besoin de la bibliothèque) et vous avez un paquet "dev" qui contient les en-têtes de la bibliothèque. Le code source n'est normalement pas fourni directement dans un package. Ce serait vraiment lourd si vous deviez obtenir le code source d'une bibliothèque quelque part pour obtenir la documentation de l'API.

35
Jesper

Nous avons résolu ce problème (il y a environ 25 ans) en créant un groupe de # définitions (par exemple publiques, privées, etc., résolues en <rien>) qui pourraient être utilisées dans le fichier source et ont été analysées par un script awk (horreurs !) 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 a considérablement simplifié ce type de documentation en ligne.

12
Peter Rowell

En supposant qu'il s'agit de code dans un projet plus grand (où les développeurs se déplaceront souvent entre la source et les en-têtes) , et fournir cela n'est pas une bibliothèque/middleware, où d'autres peuvent ne pas avoir accès à la source, j'ai trouvé que cela fonctionne mieux ...

  • En-têtes:
    Commentaires de ligne 1-2, seulement s'ils sont nécessaires.
    Parfois, les commentaires au-dessus d'un groupe de fonctions connexes sont également utiles.
  • La 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, uniquement pertinents pour un développeur modifiant le code dans le corps de la fonction.

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

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 cause le moins de problèmes à maintenir.

Enfin, pour les grands projets - il y a une tendance pas à faire de petites corrections dans un en-tête lorsque vous savez que cela va potentiellement recompiler 100 ou 1000 fichiers lorsque d'autres mettent à jour le contrôle de version - ralentissant également les erreurs de bissection.

9
ideasman42

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

6
Neil Butterworth

À mon avis (plutôt limité et biaisé), je suis une façon de penser en code pro-source. Quand je fais des morceaux en C++, je modifie habituellement le fichier d'en-tête une fois et puis je ne reviens jamais vraiment le regarder.

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

Mais c'est juste moi ...

5
MattyD

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 sa mise en œuvre) et de "développeurs" (vous et d'autres développeurs qui mettront en œuvre la bibliothèque) , puis mettez les "informations des utilisateurs" dans l'en-tête et la "note d'implémentation" dans la 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 fou de changements", que "l'interface" et la "fonctionnalité" ne changeront pas beaucoup, et ni si les commentaires d'en-tête changent trop fréquemment. En revanche, les commentaires du code source devront être synchronisés ("frais") avec le code source.

4
rwong

L'intérêt de doxygen est que vous générez la documentation et la rendez accessible ailleurs. Maintenant, toute cette documentation dans les en-têtes n'est plus qu'une ordure, ce qui rend plus difficile de repérer rapidement la déclaration de fonction requise, et peut-être ses surcharges. Un commentaire de ligne est maximum, ce qui devrait y aller, mais même cela est une mauvaise pratique. Parce que si vous modifiez la documentation dans la source, vous recompilez cette source et la reliez. Mais si vous mettez des documents dans l'en-tête, vous ne voulez vraiment rien y changer, car cela va déclencher une partie importante de la reconstruction du projet.

0
Slava