En los lenguajes que distinguen entre un archivo "fuente" y "encabezado" (principalmente C y C ++), es mejor documentar las funciones en el archivo encabezado:
(robado 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);o en el archivo fuente?
(robado 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)
{
...Tenga en cuenta que algunas cosas se definen solo en el encabezado, como estructuras, macros y static inlinefunciones. Solo estoy hablando de cosas que se declaran en un archivo de encabezado y se definen en un archivo fuente.
Aquí hay algunos argumentos en los que puedo pensar. Me estoy inclinando hacia la documentación en el archivo fuente, por lo que mis argumentos "Pro-header" pueden ser algo débiles.
Pro-encabezado:
- El usuario no necesita el código fuente para ver la documentación.
- La fuente puede ser inconveniente, o incluso imposible de adquirir.
- Esto mantiene la interfaz y la implementación más separadas.
Pro-fuente:
- Hace que el encabezado sea mucho más corto, lo que le da al lector una vista panorámica del módulo en su conjunto.
- Empareja la documentación de una función con su implementación, lo que facilita ver que una función hace lo que dice que hace.
Al responder, tenga cuidado con los argumentos basados en lo que pueden hacer las herramientas y los "IDE modernos". Ejemplos:
- Pro-header: el plegado de código puede ayudar a hacer que los encabezados comentados sean más navegables al ocultar los comentarios.
- Pro-fuente: cscope 's
Find this global definitionfunción le lleva al archivo de origen (donde la definición es) más que el archivo de cabecera (donde la declaración es).
No digo que no haga tales argumentos, pero tenga en cuenta que no todos están tan cómodos con las herramientas que usa como usted.