EST-DGT-002 Estándar para Comentarios de Código con Doxygen
v 2.0
Propósito
El propósito de este documento es establecer un estándar para la documentación de código utilizando Doxygen en los proyectos de desarrollo de software de Black Dot. Este estándar tiene como objetivo mejorar la comprensión, mantenimiento y trazabilidad del código a través de comentarios estructurados y consistentes.
Notas introductorias
Una buena documentación es crucial para el desarrollo y mantenimiento eficiente del software. Doxygen permite generar documentación de código fuente de manera automática y legible, facilitando así la colaboración y el entendimiento entre los miembros del equipo.
Estándares
Comentarios para Componentes y Funciones
Cada componente de React y función en TypeScript debe ser documentado con comentarios de Doxygen justo antes de su declaración, siguiendo este formato:
/**
* @brief Breve descripción de lo que hace el componente o función.
*
* Descripción más detallada si es necesario.
*
* @param paramName tipo: descripción del parámetro.
* @return Tipo y descripción de lo que retorna la función (si aplica).
*/
Comentarios para Clases y Interfaces
Cada clase o interface en TypeScript debe tener un comentario de Doxygen en su declaración que incluya:
/**
* @brief Breve descripción de la clase o interface.
*
* Descripción más extensa de la clase o interface, su propósito y cómo se utiliza.
*
* @tparam TName Descripción del tipo genérico si la clase o interface es una plantilla.
*/
Comentarios para Variables y Miembros de Clases
Las variables y miembros de clases o interfaces deben documentarse con comentarios de línea o de bloque antes de su declaración:
/**
* @brief Descripción detallada de la variable o miembro de clase.
*/
const myVariable: number;
Comentarios para Hooks y Custom Hooks
Los hooks y custom hooks deben ser documentados explicando su propósito, parámetros y lo que retornan, si es aplicable:
/**
* @brief Descripción del hook, qué hace y cuándo usarlo.
*
* @param paramName tipo: descripción del parámetro.
* @return Descripción de lo que retorna el hook.
*/
Control de cambios
| Versión | Cambio realizado | Análisis | Autor | Revisor(es) | Fecha de cambio |
|---|---|---|---|---|---|
| v 1.0 | Creación del estándar | N/A | Daniel Hurtado | Pendiente | 08/04/2024 |
| v 2.0 | Ajuste de formato | Se modificó el contenido del estándar de acuerdo a la plantilla porque el documento tenía información no requeridas | Yuna Chung | Ricardo Fernández | 24/04/2024 |