Nelle lingue che distinguono tra un file "sorgente" e "header" (principalmente C e C ++), è meglio documentare le funzioni nel file di intestazione:
(rubato da 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);
o nel file sorgente?
(rubged 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 structs, macros e static inline functions. Sto solo parlando di elementi dichiarati in un file di intestazione e definiti in un file sorgente.
Ecco alcuni argomenti a cui posso pensare. Sono incline a documentare nel file sorgente, quindi i miei argomenti "Pro-header" potrebbero essere un po 'deboli.
Pro-intestazione:
- L'utente non ha bisogno del codice sorgente per vedere la documentazione.
- La fonte potrebbe essere inopportuna o addirittura impossibile da acquisire.
- Ciò mantiene l'interfaccia e l'implementazione più distanti.
Pro-source:
- Rende l'intestazione molto più breve, dando al lettore una visione d'insieme 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, fai attenzione agli argomenti basati su quali strumenti e "IDE moderni" possono fare. Esempi:
- Intestazione pro: la piegatura del codice può contribuire a rendere più navigabili le intestazioni commentate nascondendo i commenti.
- Pro-source: la funzione di cscope
Find this global definitionti porta al file sorgente (dove la definizione è) piuttosto che il file di intestazione (dove la dichiarazione è).
Non sto dicendo di non formulare argomenti del genere, ma ricorda che non tutti sono a proprio agio con gli strumenti che utilizzi come sei.