c++ - for - how to document code in c

¿Doxygen, demasiado pesado para mantener?

Question

Actualmente estoy empezando a usar doxygen para documentar mi código fuente. He notado que la sintaxis es muy pesada, cada vez que modifico el código fuente, también necesito cambiar el comentario y realmente tengo la impresión de pasar demasiado tiempo modificando el comentario para cada cambio que realice en el código fuente.

¿Tienes algunos consejos para documentar mi código fuente de manera eficiente?

¿Existe algún editor (o complemento para el editor existente) para que doxygen haga lo siguiente?

• Sigue automáticamente el código / comentario no sincronizado y advierte al programador sobre ello.
• agregar automáticamente el formato de comentario de doxygen (plantilla con el nombre del parámetro en él por ejemplo) en el código fuente (plantilla) para cada nuevo elemento

PS: Estoy trabajando en un proyecto C / C ++.

Answer 1

¿Es difícil encontrar la sintaxis de Doxygen? O es el hecho de que tienes que comentar todas las funciones ahora.

Si es el primero, puede haber una herramienta diferente que se adapte mejor a su estilo de codificación. Tenga en cuenta que Doxygen admite múltiples estilos de comentarios, así que experimente hasta que encuentre uno que le guste.

Si es lo último, entonces resuélvelo. Como una buena práctica de programación, cada función pública debe tener un encabezado de comentario que explique:

1. Lo que hace la función
2. Los parametros
3. Los códigos de retorno
4. Cualquier advertencia / limitación importante sobre la función.

Esto es cierto independientemente de la herramienta de documentación que utilice.

Mi gran consejo: Evita la tentación de comentar demasiado. Describe lo que necesitas, y nada más. Doxygen te da muchas etiquetas, pero no tienes que usarlas todas.

• No siempre necesitas un resumen y una descripción detallada.
• No es necesario poner el nombre de la función en los comentarios.
• No es necesario comentar la función prototipo Y la implementación.
• No necesita el nombre del archivo en la parte superior de cada archivo.
• No necesitas un historial de versiones en los comentarios. (Estás usando una herramienta de control de versiones, ¿verdad?)
• No necesitas una "última fecha de modificación" o similar.

En cuanto a su pregunta: Doxygen tiene algunas opciones de configuración para activar advertencias cuando los comentarios no coinciden con el código. Puede integrar esto en su proceso de compilación y escanear la salida de Doxygen en busca de advertencias. Esta es la mejor manera que he encontrado para detectar desviaciones en el código frente a los comentarios.

Answer 2

Además de Doxygen, creo que deberías echar un vistazo a Code Rocket .

En realidad, documenta lo que está sucediendo "dentro" de sus métodos al rastrear el código real y los comentarios que contienen, por lo tanto, no solo se limita a los encabezados de comentarios de funciones, que pueden desactualizarse con lo que realmente son los contenidos de las funciones.

Le proporcionará automáticamente visualizaciones de diagramas de flujo y pseudocódigo de los contenidos de su método como una forma de documentación.

Answer 3

En mi experiencia profesional de software, cada vez que se modifica un archivo fuente, se debe ingresar un comentario que describa el cambio. Estos comentarios de cambios generalmente no están en las áreas de comentarios de Doxygen (a menos que se realicen cambios en una interfaz).

Te sugiero que hagas de tu código un hábito. Esto no solo es bueno para cuando otras personas tienen que mantenerlo o asistirlo con su código, sino que también ayuda cuando abandona un archivo fuente por un tiempo (como cuando la administración le dice que cambie de proyecto). Descubrí que escribir comentarios mientras codifico me ayuda a entender mejor los algoritmos.

Answer 4

Hay algo realmente malo en la forma en que usas los comentarios o en cómo te desarrollas.

Los comentarios de Doxygen se utilizan para la documentación externa / interna en las interfaces. Si sus interfaces cambian extremadamente rápido, entonces probablemente debería sentarse y pensar primero en el diseño de la arquitectura.

Si está utilizando doxygen para documentar el flujo interno de funciones, tal vez debería replantearse este enfoque (e incluso entonces, estos comentarios no deberían cambiar tanto). Cuando tiene una función que calcula algún valor, entonces un comentario /// Calculating xy using the abc algorithm es definitivamente algo que no debería cambiar cada día.

Answer 5

Juzga a ti mismo si el estilo de abajo se ajusta a tus necesidades. Es C-afín aunque, tal vez puedas sacar suficiente de él para tus fines.

////file

/// Brief description goes here
bool /// @retval 0 This is somewhat inconsistent. /n Doxygen allows several retval-descriptions but 
     /// @retval 1 will not do so for parameters. (see below)
PLL_start( 
   unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the
                           ///     comment will go also. /n
                           /// 1: Unluckily, to structure the input ranges, one has to use formatting commands like //n /n
                           /// 2-32767: whatever
   int param)              ///< 0: crash /n
                           ///  1: boom /n
                           ///  2: bang!
{
   /**
    * Here goes the long explanation. If this changes frequently, you have other more grave problems than 
    * documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS!
    * - Explain in list form.
    * - It really helps the maintainer to grok the code faster.
    *
    *@attention Explain misuses which aren''t caught at runtime.
    *
    *@pre Context:
    * - This function expects only a small stack ...
    * - The call is either blocking or non-blocking. No access to global data. 
    *
    *@post The Foobar Interrupt is enabled. Used system resources:
    *    - FOO registers 
    *    - BAR interrupts
    */
    /**@post This is another postcondition. */
}

Answer 6

No es exactamente lo que estás buscando, pero este complemento de Vim puede generar un código auxiliar de Doxygen por encima de tus definiciones. Funciona bastante bien.

Answer 7

Realmente depende de cuánta información ponga en su documentación.

Mis funciones generalmente son más pequeñas ahora debido a las pruebas unitarias y, por lo tanto, la documentación es, en consecuencia, pequeña. Además, al documentar la clase en sí, siempre tengo un pequeño fragmento de código para mostrar cómo se supone que debe usar la clase. Me parece que son los más difíciles de mantener, pero vale la pena para que no te molesten los juniors preguntándote cómo usan la clase.

Consejos:

• Sólo documente sus interfaces públicas.
• Solo realice documentación mínima sobre lo que hace la función.
• Trate de usar un editor que tenga soporte (la mayoría lo hace) o tiene un complemento.

Te alegrarás cuando vengas a editar tu código dentro de 6 meses ...

Answer 8

Siento que recuperas lo que pones en los comentarios, 5 minutos para comentar una buena clase dentro de 3 meses, cuando la clase deba ser cambiada por otra persona que no sea el autor original (de hecho, algunas veces por el autor original) tomará mucho menos tiempo para llegar a enfrentarse con.

Segundo, el soporte de documentación mencionado por David, en eclipse cuando refactoriza los nombres de los parámetros, cambiará el nombre del parámetro en su sección de documentos, por ejemplo. No estoy seguro de querer hacer algo automáticamente para ser honesto.

"cada vez que modifico el código fuente, también necesito cambiar el comentario" Podría estar documentando demasiado. Solo debería tener que cambiar la documentación de una función si el cambio requiere cambiar a cada persona que llama de alguna manera (o, si no es así, cambiar, al menos verifique que no dependan de un comportamiento obsoleto), si no estás introduciendo una nueva funcionalidad en la que confiará una nueva persona que llama. Así que en teoría no debería ser una sobrecarga masiva. Los pequeños cambios, como las optimizaciones y las correcciones de errores dentro de la función, generalmente no necesitan documentación.

Answer 9

Use comentarios no documentales para las nuevas funciones y las primeras etapas de su código. Cuando encuentre que su código está listo para publicar, puede actualizar los documentos. También evite la repetición de argumentos o nombres de funciones.

Answer 10

Use las fortalezas de Doxygen: generará descripciones de clases y métodos sin que agregue comentarios (pero no de manera predeterminada, configure EXTRACT_ALL = YES).

No documento todos los parámetros porque creo que sus nombres deberían hacer eso por ellos (*).

Estoy en contra de los complementos de documentación automática que la mayoría de las personas recomiendan porque crean comentarios genéricos que luego tendrá que mantener.

Quiero que los comentarios sean significativos: si veo un comentario, se destaca y prestaré atención.

(*) la excepción es cuando las interfaces en el código público son muy estables y algunas personas se beneficiarán de explicaciones adicionales, incluso cuando trato de evitar la documentación.