Comentarios en el código

Esta sección presenta una serie de convenciones sugeridas sobre el uso de comentarios en el código fuente del proyecto SIGIC.

⚠ IMPORTANTE
Estas convenciones deben aplicarse siempre que sean compatibles con el lenguaje utilizado, y deben alinearse con lo establecido en la guía de estilo oficial del lenguaje y el equipo, la cual tiene carácter obligatorio dentro del proyecto.

Propósito

Los comentarios en el código deben complementar la comprensión del lector, documentando únicamente lo necesario, evitando redundancias o malas prácticas.

Convenciones

Comentario pertinente

El código bien escrito se explica por sí mismo. Comenta solo para agregar contexto, aclarar decisiones, justificar excepciones o describir comportamientos no evidentes.

Lenguaje técnico

Comentarios preferentemente en inglés técnico, o en español técnico consistente, según el acuerdo del equipo. No mezclar idiomas dentro del mismo archivo.

Comentar el "por qué", no el "qué"

Ejemplo correcto:

// Se fuerza el valor para evitar un bug de la librería X en producción

Incorrecto:

// Asigna el valor de X a Y
x = Y

Comentarios confiables

Todo comentario debe ser veraz, actual y útil. Si cambia el código, se debe actualizar el comentario.

Código limpio

El código viejo, comentado como "por si acaso", debe eliminarse del repositorio.

Comentarios de documentación técnica (docstrings)

Toda función pública, clase, o módulo debe incluir un bloque de documentación al inicio. Debe indicar claramente:

Qué hace.
Qué parámetros recibe.
Qué devuelve (si aplica).
Excepciones o efectos secundarios importantes.

El formato exacto dependerá del lenguaje, pero la estructura y el contenido serán consistentes durante todas las fases de desarrollo de SIGIC y en caso de requerir ajustes deben aplicarse para una uniformidad.

Errores comunes

Ejemplo	Motivo de rechazo
`// incrementa X`	Comentario redundante; no aporta información adicional al código.
`// Código de respaldo ↓↓↓↓`	El código comentado debe eliminarse del repositorio para evitar confusión.
Bug sin rastreo asociado	Todo comentario relacionado con errores debe incluir referencia a un ticket, TODO, FIXME o mecanismo de seguimiento.

Ejemplos

Tipos de comentarios permitidos

Tipo	Descripción
Comentarios de bloque	Explican secciones o conceptos más amplios del código.
Comentarios de línea	Útiles para aclaraciones puntuales sobre una instrucción específica.
Comentarios de encabezado	Describen el propósito de un archivo, clase o función pública.
Comentarios TODO / FIXME	Marcadores útiles para mejoras o problemas conocidos.

Ejemplos correctos

JavaScript

// Este método agrupa los documentos por categoría definida por el usuario


function groupByUserCategory() { ... }

Python

# FIXME: Esta solución es temporal hasta que se actualice la API del proveedor

Java

/**


 * Exporta un reporte PDF basado en los datos de usuario.
 * TODO: agregar opción para exportar también en formato Excel.
 * @param userId Identificador del usuario.
 * @return Archivo PDF generado.
 */
public File exportUserReport(String userId) { ... }

Aplicación conforme al lenguaje

Las guías de estilo del lenguaje definirán el estilo de comentarios (uso de //, #, /* */, """ """, /** */), pero las reglas semánticas anteriores deben mantenerse sin excepción.

Todos los comentarios de las Guías oficiales de estilo forman parte del estándar de calidad del código de SIGIC y estarán sujetos a revisión. Comentarios incorrectos, desactualizados o innecesarios debe