La documentación de código es una de las tareas más subestimadas y, al mismo tiempo, más necesarias en cualquier equipo de desarrollo de software. Ya sea que trabajes en frontend, backend o equipos de datos como data engineers o data analysts, saber documentar correctamente tu código marca la diferencia entre un proyecto mantenible y uno que nadie puede continuar. La buena noticia es que herramientas de inteligencia artificial como Notion AI y ChatGPT pueden acelerar enormemente este proceso.
¿Por qué la documentación de código importa en tu organización?
Documentar no se trata solo de agregar comentarios dentro del archivo donde corre el código. Se trata de llevar esa información a repositorios de documentación oficial como Notion o GitHub, donde otras personas del equipo puedan entender el proceso, continuarlo y mejorar la estructura tanto de documentación como de código [0:25]. Muchas organizaciones carecen de esta práctica porque los desarrolladores no siempre cuentan con el tiempo o las buenas prácticas para mantener una documentación actualizada.
Aquí es donde la inteligencia artificial entra como un gran aliado. Existen distintas herramientas que automatizan buena parte del trabajo tedioso de documentar, y lo hacen con un nivel técnico sorprendentemente preciso.
¿Cómo usar Notion AI para generar un diccionario de datos?
Notion es una herramienta ampliamente utilizada a nivel empresarial para gestionar procesos, documentación técnica y cualquier tipo de registro organizacional [1:05]. Lo interesante es que Notion incorpora un motor de inteligencia artificial interno que facilita la creación de documentación técnica directamente desde la plataforma.
¿Qué es un modelo DDL y cómo documentarlo automáticamente?
Un modelo DDL (Data Definition Language) es una definición de estructura de bases de datos SQL que describe tablas, columnas y relaciones. En el ejemplo mostrado, se copia un modelo DDL dentro de Notion, se selecciona la opción Ask AI y se le indica con lenguaje natural lo que se necesita [1:30]:
- Crear una documentación técnica como diccionario de datos.
- Agregar descripciones de las columnas y las tablas del modelo.
Notion AI genera automáticamente un documento en formato Markdown que incluye:
- Estructura de tabla con nombre de columna, tipo de dato y descripción.
- Referencias y resaltado de elementos importantes.
- Descripciones creadas desde cero para columnas que no tenían ninguna, como "address" (dirección del cliente) o "phone" (número de teléfono del cliente) [2:30].
Algunas descripciones generadas pueden necesitar ajustes manuales, pero como punto de partida reduce significativamente el trabajo de documentar esquemas SQL completos.
¿Cómo documentar un script de Python con ChatGPT?
ChatGPT, junto con otros LLM como Bard o Bing Chat, permite crear distintas etapas de documentación, tanto de código específico como documentación global de procesos [3:25].
¿Qué tipo de prompt funciona mejor para documentar código?
El prompt utilizado sigue una estructura clara y efectiva [3:40]:
- Definir el rol: "eres un experto en Python y en buenas prácticas de documentación de código".
- Dar la instrucción: comentar el script y hacer una descripción de su función.
- Especificar el nivel: "utiliza documentación técnica de alto nivel".
El script de ejemplo importa la librería Tweepy para interactuar con la API de Twitter y Pandas para el manejo de datos. Sin ningún comentario previo, ChatGPT genera [4:10]:
- Comentarios por sección explicando cada bloque de código.
- Descripción de las bibliotecas utilizadas y su propósito.
- Explicación del flujo: autenticación con claves de API, creación de instancia, uso del cursor para recorrer tuits con un límite de 50, almacenamiento en lista y conversión a data frame de Pandas.
Este resultado se puede copiar directamente a Notion, generando una documentación completa y lista para compartir con el equipo [5:30].
¿Se puede usar IA para entender código de otros desarrolladores?
Estas herramientas no solo sirven para documentar código propio. También son extremadamente útiles cuando necesitas comprender código escrito por otro colaborador [6:25]. Los casos más comunes incluyen:
- Entender el propósito general de un script heredado.
- Identificar qué hace cada línea o bloque de código.
- Determinar cómo modificar una pieza específica sin romper el resto.
- Optimizar código existente llevándolo a un siguiente nivel.
Las herramientas de IA tienen un contexto amplio de librerías y lenguajes de programación, lo que les permite funcionar con cualquier lenguaje: SQL, Python, Rust, PHP, JavaScript o el que necesites [6:10].
¿Ya estás usando inteligencia artificial para documentar tus proyectos? Comparte en los comentarios qué herramienta te ha funcionado mejor y qué retos has encontrado en el proceso.
