C++: ¿Dónde escribir la documentación del código: en .cpp o en archivos .hpp?

Question

¿Dónde se acostumbra a escribir la documentación en código de clases y métodos?

¿Escribe tales bloques de documentos encima de la clase/método correspondiente en el archivo de encabezado (.hpp) o dentro del archivo de origen (.cpp)?

¿Existe una convención ampliamente respetada para tales cosas? ¿La mayoría de los proyectos C++ lo hacen de una manera y no de la otra?

¿O debería escribirse la documentación en los dos lados (es decir, en los archivos .hpp y .cpp), tal vez con una breve descripción de un lado y uno más largo del otro lado?

Lo más importante es que hay algunas consideraciones prácticas que hacen que sea más conveniente escribirlo de una manera y no de la otra. (Por ejemplo, el uso de analizadores automáticos de documentación y generadores como Doxygen ...)

Answer 1

Ambos:

• describe el diseño y el uso de la API en la cabecera: ese es su interfaz pública para los clientes.
• Describa las alternativas de implementación/problemas y decisiones en la implementación: eso es para usted - más tarde - y otros mantenedores/potenciadores, incluso alguien que revise el diseño como entrada para los próximos años del sistema de próxima generación.

comentario a nada que no sea evidente, y nada de lo que es (a menos que su instrumento de documentación es demasiado estúpida para producir buena documentación sin).

Evite poner documentos de implementación en los encabezados, ya que cambiar el encabezado significa pruebas de marca de tiempo makefile desencadenará una recompilación innecesaria para aplicaciones de cliente que incluyen su encabezado (al menos en un entorno de biblioteca comercial o empresarial). Por la misma razón, pretenda mantener la documentación del encabezado estable y utilizable, lo suficientemente buena como para que no tenga que seguir actualizándola a medida que los clientes se quejan o pidan ejemplos.

Answer 2

Si hace una biblioteca, normalmente distribuye la biblioteca compilada y los archivos de encabezado. Esto hace que sea más útil poner documentación en los archivos de encabezado.

Answer 3

Nuevamente, ambos. En cuanto a la documentación pública, es agradable estar en .h con un formato extraíble con Doxygen, por ejemplo, como comentaron otros. Me gusta mucho la forma Perl de documentar las cosas. El archivo .pl (o .pm) incluye documentación en sí misma que se puede extraer utilizando una herramienta similar a lo que hace Doxygen para el código C++. Además, Doxygen le permite crear varias páginas diferentes, que le permiten incluir manuales de usuario, etc., no solo documentando el código fuente o la API. En general, me gusta la idea de un archivo .h/.hpp autónomo en la filosofía de la programación alfabetizada.

Answer 4

Personalmente me gusta la documentación en los archivos de cabecera. Sin embargo, hay algunos que creen que la documentación debe colocarse en los archivos fuente. La razón es que cuando algo cambia, la documentación está justo allí recordándote que la actualices. Estoy un tanto de acuerdo, ya que personalmente me olvidé de actualizar los comentarios Doxygen en el encabezado cuando cambié algo en los archivos fuente.

Todavía prefiero que los comentarios de Doxygen estén en el archivo de encabezado por razones estéticas, y los viejos hábitos son difíciles de cambiar. He intentado ambos y Doxygen ofrece la flexibilidad de documentar en archivos fuente o de encabezado.

Answer 5

que es más importante, ¿hay algún consideraciones prácticas que hace que sea más conveniente escribirlo de una manera en lugar de a la inversa?

Supongamos que desea agregar una aclaración a uno de sus comentarios sin cambiar el código. El problema es que su sistema de compilación solo verá que usted modificó el archivo y supondrá innecesariamente que necesita ser recompilado.

Si los comentarios están en el archivo .cpp, solo recompilará ese archivo. Si los comentarios están en el archivo .hpp, recompilará cada archivo .cpp que depende de ese encabezado. Esta es una buena razón para preferir tener sus comentarios en los archivos .cpp.

(por ejemplo, la uso de analizadores automáticos de documentación y generadores como Doxygen ...)

Doxygen le permite escribir sus comentarios de cualquier manera.