Utilidades IACómo documentar código con ayuda de un asistente de IA
| Para quién | Para quien mantiene o hereda un proyecto con poca documentación y quiere explicar mejor su código a su equipo, a futuros colaboradores o a sí mismo. |
|---|---|
| Tiempo estimado | 20 a 90 minutos por módulo pequeño, incluida la revisión de exactitud |
| Categoría | Programación y datos |
Paso a paso
- Decide a quién va dirigida
La documentación útil depende del lector: una persona que usará tu librería necesita ejemplos de uso; quien mantiene el código necesita las razones de las decisiones; alguien nuevo necesita una visión general. Define el público y el nivel técnico antes de pedir nada. Así evitas textos que explican lo obvio línea por línea y no dicen lo importante: el propósito, los límites y los motivos de las decisiones. - Elige qué documentar
No todo merece el mismo detalle. Prioriza la API pública, las funciones complejas, los supuestos no evidentes, el formato de los datos de entrada y salida, los errores que pueden lanzarse y la forma de instalar y ejecutar el proyecto. Evita comentarios que repiten lo que el código ya dice con claridad. Un código con buenos nombres necesita menos comentarios, y a veces la mejor documentación es renombrar una variable. - Facilita el código y su contexto
Pega el fragmento que quieres documentar junto con una breve explicación del propósito del módulo, las convenciones de documentación que sigue tu proyecto y un ejemplo de comentario existente que te guste. Retira secretos, rutas internas y datos reales antes de pegar. Indica el idioma de la documentación. Con ese contexto el asistente imitará tu estilo en lugar de inventar uno distinto y poco coherente. - Pide borradores por capas
Solicita primero un resumen de qué hace el módulo, luego la documentación de cada función con parámetros, valores devueltos, excepciones y un ejemplo breve de uso. Después, si hace falta, un apartado de instalación y uso para el archivo principal de lectura. Trabajar por capas facilita la revisión y permite corregir pronto un malentendido. Pide que marque con claridad cualquier suposición que no pueda deducir del código. - Contrasta cada afirmación con el código
Lee cada frase y comprueba que corresponde al comportamiento real. Los asistentes tienden a describir lo que una función suele hacer por su nombre, no lo que hace de verdad, y pueden omitir efectos secundarios o casos de error. Ejecuta los ejemplos incluidos para asegurarte de que funcionan tal como se muestran. Corrige lo impreciso y elimina cualquier explicación que no puedas respaldar. - Mantén la documentación junto al código
Guarda la documentación en el repositorio, cerca del código, y actualízala en el mismo cambio que modifica el comportamiento. Considera usar herramientas de tu ecosistema que generen documentación a partir de los comentarios. Añade una comprobación en el proceso de revisión: si cambia una función, ¿se ha revisado su descripción? Una documentación desactualizada es peor que ninguna porque induce a errores con apariencia de autoridad.
Prompt de ejemplo
Adáptalo sustituyendo lo que va entre corchetes:
Documenta el siguiente código de [LENGUAJE] para [PÚBLICO, POR EJEMPLO DESARROLLADORES QUE VAN A USAR ESTA FUNCIÓN]. Escribe en español y sigue este formato de comentarios: [FORMATO O CONVENCIÓN DEL PROYECTO]. Propósito del módulo: [DESCRIPCIÓN BREVE]. Código: [PEGA AQUÍ EL FRAGMENTO, SIN SECRETOS NI DATOS REALES] Para cada función quiero: una descripción de una o dos frases de lo que hace, la lista de parámetros con su tipo y significado, el valor que devuelve, los errores o excepciones posibles y un ejemplo de uso corto. Reglas: describe solo lo que se puede deducir del código; si algo es una suposición, márcalo con la etiqueta SUPOSICIÓN; no repitas lo evidente; no inventes comportamientos. Al final lista las partes del código que te parecen ambiguas o que sería mejor aclarar con cambios de nombres.
Qué esperar
Es habitual obtener borradores bien redactados y consistentes en poco tiempo, útiles para ahorrar trabajo mecánico. La parte que sigue exigiendo criterio humano es la exactitud: el asistente puede describir con soltura comportamientos que el código no tiene o pasar por alto efectos secundarios.
Cómo verificar el resultado
- Leer cada descripción y comprobar que coincide con el comportamiento real del código, incluidos los casos de error.
- Ejecutar todos los ejemplos de uso incluidos en la documentación y confirmar que producen lo indicado.
- Pedir a otra persona que no conozca el módulo que lo use siguiendo solo la documentación.
- Revisar que no se han filtrado rutas internas, claves, nombres de clientes u otros datos sensibles.
Errores comunes
- Publicar la documentación generada sin contrastarla con el comportamiento real del código.
- Comentar cada línea con lo obvio y dejar sin explicar las decisiones importantes.
- Dejar que la documentación se desactualice al cambiar el código.
- Pegar código con credenciales, direcciones internas o datos reales para que el asistente lo documente.
Riesgos y límites
El asistente documenta lo que cree que hace el código a partir de nombres y estructura, y puede describir comportamientos inexistentes, ejemplos que no funcionan o parámetros erróneos. Una documentación incorrecta con tono seguro es especialmente dañina. No pegues código confidencial ni con secretos sin comprobar las políticas de tu organización. Si tu proyecto tiene licencia o requisitos de atribución, no añadas texto que sugiera una autoría o garantía que no corresponde. Revisa siempre antes de publicar y conserva la responsabilidad editorial de lo que figure como documentación oficial.
Preguntas frecuentes
¿Es suficiente con que el asistente comente cada función?
No. Los comentarios automáticos suelen repetir lo evidente. Es más valioso explicar el porqué de las decisiones, los supuestos y los límites. Pide explícitamente eso y elimina lo redundante para que la documentación aporte información que el código no muestra.
¿Cómo detecto si la documentación es incorrecta?
Ejecuta los ejemplos, prueba los casos de error descritos y pide a alguien que use el módulo solo con esa guía. Lo más seguro es contrastar frase a frase con el código; las descripciones que suenan bien pero no puedes respaldar deben eliminarse.
¿Puede ayudar a documentar código heredado que no entiendo?
Puede darte una primera explicación útil, pero trátala como hipótesis. Compruébala ejecutando el código con ejemplos, leyendo pruebas existentes y preguntando a quien lo conozca. Documentar un comportamiento mal entendido propaga el error al resto del equipo.