¿Es mejor documentar funciones en el archivo de encabezado o en el archivo fuente?

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.

Mi vista...

• Documente cómo usar la función en el archivo de encabezado, o más exactamente cerca de la declaración.

• Documente cómo funciona la función (si no es obvio por el código) en el archivo fuente, o más exactamente, cerca de la definición.

Para el aspecto de ojo de pájaro en el encabezado, no necesariamente necesita la documentación que se cierra; puede documentar grupos de declaraciones a la vez.

En términos generales, la persona que llama debe estar interesada en los errores y excepciones (aunque solo sea para poder traducirlos a medida que se propagan a través de las capas de abstracción), por lo que estos deben documentarse cerca de las declaraciones relevantes.

Si va a utilizar una herramienta como Doxygen (tenga en cuenta en el primer ejemplo que realmente parece un comentario de Doxygen porque comienza con /**), entonces realmente no importa: Doxygen mirará a través de su encabezado y archivos fuente y encontrará Todos los comentarios para generar la documentación.

Sin embargo, estaría más inclinado a poner los comentarios de la documentación en los encabezados, donde están las declaraciones. Sus clientes se ocuparán de los encabezados para interactuar con su software, los encabezados son lo que incluirán en sus propios archivos fuente y allí es donde buscarán primero para ver cómo se ve su API.

Si observa la mayoría de las bibliotecas de Linux, por ejemplo, su sistema de administración de paquetes de Linux a menudo tiene un paquete que contiene solo los binarios de la biblioteca (para usuarios "normales" que tienen programas que necesitan la biblioteca) y usted tiene un paquete "dev" que contiene los encabezados para la biblioteca. El código fuente normalmente no se suministra directamente en un paquete. Sería realmente engorroso si tuviera que obtener el código fuente de una biblioteca en algún lugar para obtener la documentación de la API.

Resolvimos este problema (hace aproximadamente 25 años) creando un grupo de #defines (p. Ej., Públicos, privados, etc., que se resolvieron en <nada>) que podrían usarse en el archivo fuente y fueron escaneados por un script awk (horrores !) para generar automáticamente los archivos .h. Esto significa que todos los comentarios vivieron en la fuente y se copiaron (cuando corresponde) en el archivo .h generado. Sé que es bastante Old School, pero simplificó enormemente este tipo de documentación en línea.

Asumiendo que esto es código dentro de un proyecto más grande (donde los desarrolladores se moverán entre la fuente y los encabezados a menudo) , y siempre que esto no sea una biblioteca / middleware, donde otros pueden no tener acceso a la fuente, he encontrado que esto funciona mejor...

• Encabezados:
  comentarios breves de 1-2 líneas, solo si son necesarios.
  A veces, los comentarios sobre un grupo de funciones relacionadas también son útiles.
• Fuente:
  documentación en API directamente sobre la función (texto plano o doxygen si lo prefiere) .
• Mantenga los detalles de implementación, solo relevantes para un desarrollador que modifique el código en el cuerpo de la función.

La razón principal de esto es para mantener los comentarios cerca del código, he notado que los documentos en los encabezados tienden a desincronizarse con los cambios en el código con más frecuencia. (por supuesto que no deberían, pero lo hicieron en nuestro proyecto en menos) . También los desarrolladores pueden agregar documentación en la parte superior de las funciones cuando realizan algún cambio, incluso si hay documentos de encabezado ... en otro lugar. Causar duplicaciones o información útil solo para estar en una de las cadenas de documentos.

Por supuesto, puede elegir una convención y asegurarse de que todos los desarrolladores la sigan, acabo de encontrar la convención por encima del ajuste más natural y causa menos problemas para mantener.

Por último, para proyectos grandes, existe la inclinación de no hacer pequeñas correcciones en un encabezado cuando se sabe que puede causar que se vuelvan a compilar potencialmente 100 o 1000 de archivos cuando otros actualizan el control de versión, lo que también ralentiza los errores de bisección.

En mi opinión (bastante limitada y sesgada), soy una forma de pensar de código fuente. Cuando hago partes en C ++, generalmente edito el archivo de encabezado una vez y luego nunca vuelvo a mirarlo.

Cuando coloco documentación en el archivo fuente, siempre la veo cuando estoy editando o leyendo códigos. Supongo que es una costumbre.

Pero solo soy yo ...

Los comentarios no son documentación. La documentación para una función normalmente puede ser de 2K de texto, posiblemente con diagramas; consulte, por ejemplo, la documentación para funciones en el SDK de Windows. Incluso si su comentario a documento permite tal cosa, hará que el código que contiene el comentario sea ilegible. Si desea producir documentación, use un procesador de textos.

Si las partes interesadas de su código fuente (por ejemplo, una pequeña biblioteca) se componen de "usuarios" (otros desarrolladores que utilizarán la funcionalidad de su biblioteca sin involucrarse en su implementación) y "desarrolladores" (usted y otros desarrolladores que implementarán la biblioteca) , luego coloque la "información de los usuarios" en el encabezado y la "nota de implementación" en la fuente.

Con respecto al deseo de no cambiar los archivos de encabezado más de lo absolutamente necesario, supongo que si su biblioteca no está "en un flujo loco de cambios", que la "interfaz" y la "funcionalidad" no cambiarán mucho, y tampoco Si los comentarios del encabezado cambian con demasiada frecuencia. Por otro lado, los comentarios del código fuente deberán mantenerse sincronizados ("nuevos") con el código fuente.

El objetivo de usar doxygen es que genera documentación y la hace accesible en otro lugar. Ahora toda esa documentación en los encabezados es solo basura, lo que hace que sea más difícil detectar rápidamente la declaración de función requerida, y tal vez sus sobrecargas. Un comentario de línea es el máximo que debería ir allí, pero incluso eso es una mala práctica. Porque si cambia la documentación en la fuente, recompila esa fuente y vuelve a vincularla. Pero si coloca documentos en el encabezado, realmente no desea cambiar nada, porque provocará una parte importante de la reconstrucción del proyecto.