Comentario de código de doble propósito (usuarios y mantenedores) ... ¿CÓMO?

Estoy escribiendo una biblioteca estática de C++ y he estado comentando con los comentarios de doxygen en los archivos de implementación. Nunca tuve que preocuparme mucho por la documentación, pero ahora estoy trabajando en algo que debe documentarse bien para los usuarios y también estoy tratando de reemplazar mi mal hábito anterior de solo querer codificar y no documentar con una mejor ingeniería de software. prácticas.Comentario de código de doble propósito (usuarios y mantenedores) ... ¿CÓMO?

De todos modos, el otro día me di cuenta de que necesito un par de tipos diferentes de documentación, un tipo para usuarios de la biblioteca (manual de doxygen) y luego comentarios para mí o un futuro mantenedor que se ocupe más de los detalles de implementación.

Una de mis soluciones es colocar los comentarios doxygen para el archivo, la clase y los métodos en la parte inferior del archivo de implementación. Allí estarían fuera del camino y podría incluir comentarios normales en/alrededor de las definiciones del método para beneficiar a un programador. Sé que es más trabajo, pero me parece la mejor manera de lograr los dos tipos de comentarios/documentación por separado. ¿Está de acuerdo o tiene alguna solución/principio que podría ser útil? Miré alrededor del sitio pero no pude encontrar ningún hilo que tratara con esto.

Además, realmente no quiero ensuciar el archivo de interfaz con comentarios porque siento que es mejor dejar que la interfaz hable por sí misma. Preferiría que el manual sea el lugar donde el usuario puede mirar si necesita una comprensión más profunda de la interfaz de la biblioteca. ¿Estoy en el camino correcto aquí?

Cualquier idea o comentario es muy apreciada.

editar: Gracias a todos por sus comentarios. He aprendido mucho de escucharlos. Creo que entiendo mejor cómo separar el manual de usuario de los comentarios del código que serán útiles para el mantenedor. Me gusta la idea que tiene @jalf de tener un manual de estilo en "prosa" que ayude a explicar cómo usar la biblioteca. Realmente creo que esto es mejor que solo un manual de referencia. Dicho eso ... también siento que el manual de referencia podría ser útil. Creo que combinaré sus consejos con los pensamientos de los demás e intentaré crear un híbrido. (Un manual en prosa (usando las etiquetas doxygen como página, sección, subsección) que enlaza con el manual de referencia.) Otra sugerencia que me gustó de @jalf era la idea de que el código no tuviera todo un manual intercalado. Puedo evitar esto colocando todos mis comentarios doxygen en la parte inferior del archivo de implementación. Eso deja los encabezados limpios y la implementación limpia para colocar comentarios útiles para alguien que mantiene la implementación. Veremos si esto funciona en la realidad. Estos son solo mis pensamientos sobre lo que he aprendido hasta ahora. No estoy seguro de que mi enfoque vaya a funcionar bien o incluso que sea práctico. Sólo el tiempo dirá.

Fuente

2010-01-19 csmithmaui

Por lo general, creo que los comentarios para los usuarios deberían ser no estar en línea en el código, como comentarios doxygen o algo por el estilo. Debe ser un documento separado, en forma de prosa. Como usuario de la biblioteca, no necesito ni quiero saber qué significa cada parámetro para una función. Con suerte, eso es obvio. Necesito saber qué función tiene . Y necesito saber por qué lo hace y cuando para llamarlo. Y necesito saber qué condiciones previas y posteriores se aplican. ¿Qué suposiciones hace la función cuando la llamo, y qué garantías proporciona cuando vuelve?

Los usuarios de la biblioteca no necesitan comentarios, necesitan documentación.Describa cómo está estructurada la biblioteca y cómo funciona y cómo usarla, y hazlo fuera del código, en un documento de texto real.

Por supuesto, el código aún puede contener comentarios dirigidos a los mantenedores, explicando por qué la implementación se ve de la manera que lo hace, o cómo funciona si no es obvio. Pero la documentación que el usuario de la biblioteca necesita no debe estar en el código.

Fuente

2010-01-19 03:10:56 jalf

gracias jalf ... esto también tiene mucho sentido para mí. Estaba pensando que mi documentación generada por doxygen podría ser un poco difícil de leer para un usuario. En cierto modo, es agradable, pero sentía que faltaba una explicación real sobre cómo usar la biblioteca, pero pensé que tal vez debería ser más descriptivo. Una pregunta: ¿Tendría algún uso para doxygen teniendo en cuenta sus comentarios anteriores? – csmithmaui

Yo personalmente no lo haría. Pero esa es mi opinión subjetiva. Tengo necesidades muy diferentes al leer el código y al leer la documentación. En la documentación, quiero detalles. Quiero una descripción de alto nivel y todos los detalles y la semántica. Y está bien que ocupe mucho espacio. En el código sin embargo? Screen Estate es una prima. Cada línea es costosa, reduce la cantidad de código que puedo ver, y por lo tanto me impide formar una visión general del código. En el código quiero el menor ruido posible, y * quiero * que la mayor parte de la información quede fuera, y los comentarios sean breves. – jalf

fantástica descripción de cuándo y cómo agregar comentarios. Pero no estoy de acuerdo con que toda esta descripción * tenga * fuera del código. Dónde se guardan los comentarios no es una gran preocupación para mí. –

Creo que el mejor enfoque es usar Doxygen para archivos de encabezado para describir (a los usuarios) cómo usar cada clase/método y usar comentarios dentro de los archivos .cpp para describir los detalles de implementación.

Fuente

2010-01-19 02:18:58

Gracias por el comentario Kyle. Tiene sentido, mi única preocupación sería el tamaño del archivo de encabezado y, a veces, mis comentarios doxygen pueden ser algo crípticos para obtener el formato correcto para el manual, lo que deja el archivo de encabezado grande y difícil de leer. Todavía podría ser la mejor opción, tendré que pensar si es más. Gracias de nuevo. – csmithmaui

Si tiene un archivo de encabezado completamente comentado, solo remitiría a los usuarios a la documentación generada en lugar de que ellos lean el archivo de encabezado. –

ahh ... Ya veo. ¡Vale gracias! – csmithmaui

Bien hecho, los comentarios de Doxygen pueden ser muy útiles tanto al leer el código como al leer el código HTML generado. Toda la dificultad se encuentra en Bien hecho.

Mi enfoque es el siguiente:

Para los usuarios de la biblioteca, puse comentarios Doxygen en los archivos de cabecera para explicar cuál es el propósito de esta función y cómo usarlo, detallando todos los argumentos, valores devueltos y posibles efectos secundarios. Intento formatearlo de modo que la documentación generada sea un manual de referencia.
Para los mantenedores, pongo comentarios básicos (no Doxygen) en los archivos de implementación cuando el código de autocomentario no es suficiente.

Por otra parte, os escribo un archivo especial de introducción (aparte del código) en formato Doxygen para explicar a los nuevos usuarios de libray cómo utilizar las distintas funciones de la biblioteca, en la forma de una guía de usuario, que puntos a los detalles del manual de referencia. Esta introducción aparece como la página principal de la documentación generada por Doxygen.

Fuente

2010-01-19 12:45:25 mouviciel

mouviciel, es el "archivo introductorio especial" solo un archivo de texto y ¿lo pusiste? ¿Se vincula automáticamente al manual de referencia cuando escribe el nombre de las clases, archivos, espacios de nombres, etc. o tiene que ser más explícito? Este enfoque parece ser un híbrido entre un "manual en prosa" como @jalf explicado y un viejo y simple "manual de referencia". Me gusta la idea. – csmithmaui

Este puede ser un archivo de texto separado con etiquetas Doxygen (por ejemplo, @page, @section, ...) o una parte de la documentación del archivo de encabezado principal de su biblioteca. Doxygen se vincula automáticamente al manual de referencia. De hecho, es la primera página de la documentación de Doxygen. – mouviciel

bien ... eso tiene sentido. Muchas gracias. – csmithmaui

Doxygen permite la creación de dos versiones de la documentación (una para usuarios y otra para "uso interno") a través del comando \internal y la opción INTERNAL_DOCS. También es posible tener un grano más fino de control con secciones condicionales (véase el comando \if y la opción ENABLED_SECTIONS.)

como ya se ha señalado, también es útil para proporcionar a los usuarios (y también los mantenedores veces) algo en una nivel más alto que estrictamente comentarios de código. Doxygen también se puede utilizar para que, con la \mainpage, \ página, [sub [sub]] sección y \ par comandos

Fuente

2010-01-19 14:04:51

Gracias Eric ... ¡No estaba al tanto de esto! – csmithmaui

Por supuesto, yo diría que esto realmente no resuelve el problema con doxygen. No necesita Doxygen para escribir esta documentación de alto nivel. Abra el Bloc de notas si desea escribir texto. O tu procesador de palabras favorito O (mi preferido) crear un documento TeX. El hecho de que Doxygen defina campos para la documentación que realmente necesita escribir no significa que se vuelva de alguna manera más clara o más fácil de escribir simplemente poniéndolo en Doxygen. Aún tienes que escribir el mismo texto. Ahora solo tiene que estar dentro de los impuestos doxygen, y tiene que estar en el código fuente. Pero no te ahorra ningún trabajo. – jalf

@jalf: Obviamente, tienes que escribir el mismo texto. Sin embargo, a menudo es útil poder consultar la documentación de las fuentes a partir de ese texto, y viceversa. –

Te recomiendo echar un vistazo a este artículo: http://www.literateprogramming.com/knuthweb.pdf

normalmente aplicado dichas ideas para mis proyectos (usando Doxygen). También ayuda a mantener el documento actualizado ya que no es necesario abandonar el IDE, por lo que se pueden hacer anotaciones durante la codificación y, posteriormente, revisar el documento final en formato pdf para ver qué necesita actualizarse o detallarse.

En mi experiencia, Doxygen requiere un poco de trabajo para que el pdf se vea bien, los gráficos y las imágenes en su lugar, etc. pero una vez que encuentre las formas y conozca las limitaciones de la herramienta, hará el trabajo bastante bien.

Mi sugerencia, además de lo que Kyle Lutz y Eric Malefant ya han dicho, es poner explicaciones largas sobre las clases relacionadas en su propio archivo (uso un archivo de encabezado para eso) y agregar referencias a otras partes usando etiquetas Doxygen. Solo necesita incluir esos encabezados en el archivo de configuración de Doxygen (usando la coincidencia de patrones). Esto evita abarrotar demasiado tus encabezados.

Fuente

2010-01-19 21:08:29

No hay una respuesta rápida fácil, la buena documentación es difícil.

Personalmente siento que un modelo en capas es el mejor.

documentos de alto nivel en prosa. Las fotos y los videos son muy apropiados.
doc. De nivel de referencia debe Doxygen (Doxygen bien hecho, no solo comentarios de mano).
los documentos del mantenedor no deberían aparecer en los documentos de referencia, pero aún podrían ser doxygen como señala Éric.

Me gusta mucho el estilo de documentación utilizado en RakNet. El autor usa extensos comentarios de Doxygen y proporciona un reference manual generado. También proporciona algunos plain html tutorials. Lo mejor de todo es que proporciona video walk-throughs de algunas de las funciones más complicadas.

Otro buen ejemplo es SFML. La calidad no es tan buena como RakNet, pero sigue siendo muy buena. Él proporciona una buena página de resumen en el doxygen generated documentation. Hay unos pocos plain html tutorials y una página de características/descripción general de html.

Prefiero estos estilos ya que la documentación generada por Doxygen es generalmente de un nivel demasiado bajo cuando recién estoy comenzando, pero perfectamente concisa una vez que estoy en la rutina.

Fuente

2010-02-10 17:08:20

Comentario de código de doble propósito (usuarios y mantenedores) ... ¿CÓMO?

Respuesta

Cuestiones relacionadas