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 inline
fonctions. 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 definition
fonction 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.