c++ - que - encabezado programacion
C++: ¿Dónde escribir la documentación del código: en.cpp o en archivos.hpp? (5)
¿Dónde es habitual escribir la documentación en el código de clases y métodos?
¿Escribe dichos doc-blocks encima de la clase / método correspondiente en el archivo del encabezado (.hpp), o dentro del archivo fuente (.cpp)?
¿Existe una convención ampliamente respetada para tales cosas? ¿La mayoría de los proyectos de C ++ lo hacen de una manera en lugar de la otra?
¿O debería escribirse la documentación en los dos lados (es decir, en los archivos .hpp y .cpp), quizás con una breve descripción de un lado y una más larga del otro lado?
Más importante aún, ¿existen consideraciones prácticas que lo hagan más conveniente para escribirlo de una manera en lugar de la otra? (Por ejemplo, el uso de analizadores automáticos de documentación y generadores como Doxygen ...)
Más importante aún, ¿existen consideraciones prácticas que lo hagan más conveniente para escribirlo de una manera en lugar de la otra?
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 ha cambiado el archivo y supone innecesariamente que necesita ser recompilado.
Si los comentarios están en el archivo .cpp, solo volverá a compilar ese archivo. Si los comentarios están en el archivo .hpp, volverá a compilar cada archivo .cpp que dependa de ese encabezado. Esta es una buena razón para preferir tener sus comentarios en los archivos .cpp.
(Por ejemplo, el uso de analizadores automáticos de documentación y generadores como Doxygen ...)
Doxygen te permite escribir tus comentarios de cualquier manera.
De nuevo, ambos. En cuanto a la documentación pública, es bueno estar en .h con un formato extraíble con Doxygen, por ejemplo, como comentaron otros. Me gusta mucho la forma en que Perl documenta las cosas. El archivo .pl (o .pm) incluye documentación en sí misma que puede extraerse utilizando una herramienta similar a la 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 documentar el código fuente o API. En general, me gusta la idea de un archivo .h / .hpp autónomo en la filosofía de la programación alfabetizada.
Personalmente me gusta la documentación en los archivos de cabecera. Sin embargo, hay algunos que creen que la documentación se debe colocar en los archivos de origen. La razón es que cuando algo cambia, la documentación está ahí, recordándole que lo actualice. Estoy algo de acuerdo, ya que personalmente he olvidado actualizar los comentarios de Doxygen en el encabezado cuando cambié algo en los archivos de origen.
Sigo prefiriendo que los comentarios de Doxygen estén en el archivo del encabezado por razones estéticas, y los viejos hábitos son difíciles de cambiar. He probado ambos y Doxygen ofrece la flexibilidad de documentar en archivos de fuente o de encabezado.
Si crea una biblioteca, normalmente distribuye la biblioteca compilada y los archivos de encabezado. Esto hace que sea más útil colocar documentación en los archivos de encabezado.
Ambos:
- Describa el diseño y el uso de la API en el encabezado: esa es su interfaz pública para los clientes.
- Describa las alternativas / problemas y decisiones de implementación en la implementación: eso es para usted, más adelante, y para otros mantenedores / mejoradores, incluso para alguien que revise el diseño como entrada para algunos años del sistema de próxima generación.
Comente cualquier cosa que no sea obvia, y nada que sea (a menos que su herramienta de documentación sea demasiado estúpida para producir buena documentación sin ella).
Evite colocar documentos de implementación en los encabezados, ya que cambiar el encabezado significa que las pruebas de marca de tiempo de makefile activarán una recompilación innecesaria para las aplicaciones cliente que incluyen su encabezado (al menos en un entorno de biblioteca comercial o empresarial). Por el mismo motivo, intente mantener la documentación del encabezado estable y utilizable, lo suficientemente bueno como para no tener que seguir actualizándola, ya que los clientes se quejan o piden ejemplos.