Nei linguaggi che distinguono tra un file "source" e "header" (principalmente C e C ++), è meglio documentare le funzioni nel file header:
/**
* 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);
o nel file sorgente?
(rubato da 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)
{
...
Nota che alcune cose sono definite solo nell'intestazione, come le strutture, le macro e le static inlinefunzioni. Sto solo parlando di cose che sono dichiarate in un file header e definite in un file sorgente.
Ecco alcuni argomenti che mi vengono in mente. Mi sto impegnando per documentare nel file sorgente, quindi i miei argomenti "Pro-header" potrebbero essere piuttosto deboli.
Pro-intestazione:
- L'utente non ha bisogno del codice sorgente per vedere la documentazione.
- La fonte potrebbe essere scomoda o addirittura impossibile da acquisire.
- Ciò mantiene ulteriormente l'interfaccia e l'implementazione.
Pro-source:
- Rende l'intestazione molto più breve, offrendo al lettore una visione a volo d'uccello del modulo nel suo insieme.
- Associa la documentazione di una funzione alla sua implementazione, rendendo più facile vedere che una funzione fa quello che dice di fare.
Quando rispondi, ti preghiamo di diffidare delle argomentazioni basate su quali strumenti e "IDE moderni" possono fare. Esempi:
- Pro-header: la piegatura del codice può aiutare a rendere più navigabili le intestazioni commentate nascondendo i commenti.
- Pro-source: cscope 's
Find this global definitionfunzione vi porta al file di origine (in cui la definizione è) piuttosto che il file di intestazione (in cui la dichiarazione è).
Non sto dicendo di non fare simili argomenti, ma tieni presente che non tutti sono a proprio agio con gli strumenti che usi come sei.