El objetivo de un buen comentario no es explicar qué hace el código (eso debería ser evidente por la sintaxis), sino por qué se tomó esa decisión o qué reglas de negocio rigen esa lógica. ChatGPT es una herramienta excepcional para esta tarea porque puede analizar el contexto y redactar explicaciones claras en el estándar que prefieras.
1. La Diferencia entre Comentarios Útiles y Redundantes
Antes de automatizar, es vital distinguir entre un comentario que aporta valor y uno que ensucia el archivo. ChatGPT puede ayudarte a limpiar el «ruido».
- Mal comentario:
x = x + 1 // Incrementa x en 1(Redundante). - Buen comentario:
x = x + 1 // Ajuste necesario para compensar el desfase del índice en el sensor externo(Aporta contexto).
2. Generación de Docstrings Estándar
Para lenguajes como Python, Java o JavaScript, existen formatos específicos que permiten generar documentación automática (como Sphinx o JSDoc). La IA domina estas estructuras.
- Prompt de configuración:«Actúa como un Documentalista Técnico. Analiza la siguiente función y genera los comentarios en formato [JSDoc / Google Style Docstrings / Doxygen]. Incluye una descripción breve, los parámetros con su tipo y el valor de retorno. [Pegar Código].»
3. Explicación de Lógica Compleja o Algoritmos
Cuando implementas una fórmula matemática o un algoritmo denso, un comentario de una sola línea no es suficiente. Puedes pedirle a la IA que cree una «guía visual» en texto.
| Tipo de Lógica | Estrategia de Comentario | Beneficio |
| Regex | Explicar cada grupo de captura. | Facilita la depuración de patrones crípticos. |
| Fórmulas | Referenciar la fuente o el propósito del cálculo. | Valida la base científica del código. |
| Workarounds | Explicar por qué no se usó la solución estándar. | Evita que otros desarrolladores «corrijan» el código y lo rompan. |
4. El «Prompt Maestro» para Documentar un Módulo Completo
Si tienes un archivo con varias funciones relacionadas, utiliza este bloque de instrucciones para mantener la coherencia:
«Actúa como un Ingeniero de Software Senior.
Tarea: Documenta profesionalmente este módulo.
- Encabezado: Añade un comentario inicial que explique el propósito del archivo y sus dependencias.
- Legibilidad: Identifica los bloques de lógica más complejos y añade comentarios ‘inline’ que expliquen el flujo.
- Advertencias: Indica si alguna función tiene efectos secundarios (como modificar una variable global).
- Estilo: Usa un tono profesional y conciso, evitando obviedades.»
5. Traducir Código a Lenguaje Humano para No Programadores
A veces, el comentario más útil es aquel que explica la lógica de negocio a un Product Manager o a un cliente dentro del mismo repositorio.
- Prompt de traducción: «Escribe comentarios para este script de tal forma que alguien que entiende el negocio pero no sabe programar pueda seguir qué decisiones toma el software en cada paso».
6. Revisión y Refactorización de Comentarios Existentes
Si has heredado un proyecto con comentarios en inglés mal escritos o desactualizados, ChatGPT puede actualizarlos.
- Técnica de actualización: «Revisa los comentarios de este código. Tradúcelos al español, mejora su gramática y asegúrate de que realmente reflejen lo que el código está haciendo actualmente. Si algún comentario es contradictorio, señálalo».
Conclusión
Generar comentarios con ChatGPT no es una excusa para escribir código sucio, sino una oportunidad para alcanzar la excelencia técnica. Un código bien documentado reduce drásticamente el tiempo de onboarding y minimiza los malentendidos en las revisiones de código. Deja que la IA se encargue de la redacción, mientras tú te aseguras de que el contenido sea preciso y valioso.
