- La programación literaria (Literate Programming), que entrelaza el código y las explicaciones en lenguaje natural en una sola narrativa, no logró adoptarse de forma amplia por la carga de mantener en paralelo tanto el código como la explicación, pero los agentes de codificación con IA pueden eliminar ese trabajo central
- Con
org-babel de Emacs Org Mode es posible la programación literaria multilenguaje, pero en proyectos grandes el proceso engorroso de extraer el código fuente (tangling) se vuelve una limitación
- Si se le indica al agente que escriba un runbook basado en archivos Org, se vuelve posible un flujo de trabajo donde la intención se desarrolla en explicaciones, los bloques de código se ejecutan de forma interactiva y los resultados se guardan en el documento
- Como el agente sincroniza automáticamente la explicación, el código y el tangling, desaparece el esfuerzo de reescribir las explicaciones cuando cambia el código, aprovechando además las capacidades de traducción y resumen en las que los LLM destacan
- En una tendencia donde el rol del ingeniero cambia de escribir código a leer código, la utilidad práctica de una base de código narrativa mantenida por agentes surge como una pregunta clave
El concepto y las limitaciones de la programación literaria
- La programación literaria (Literate Programming) es la idea de mezclar código y explicaciones en lenguaje natural para que incluso un lector sin conocimientos previos pueda leer una base de código como una narrativa y entender cómo funciona
- Es una idea atractiva, pero en la práctica implica la carga de mantener dos narrativas paralelas, el propio código y su explicación, y esa ha sido la razón fundamental que ha limitado su adopción
- Su forma más común en la práctica son los cuadernos Jupyter de la comunidad de ciencia de datos, donde explicación, cálculo y resultados se muestran juntos en el navegador web
Emacs Org Mode y la programación literaria
- Emacs Org Mode admite la programación literaria multilenguaje mediante el paquete
org-babel, lo que permite ejecutar cualquier lenguaje y capturar los resultados en el documento
- Aun así, este enfoque sigue siendo un patrón de nicho reservado para un pequeño grupo de usuarios entusiastas
- Si se usan archivos Org como la fuente de verdad del código en proyectos de software grandes, entonces el código fuente se vuelve en la práctica un artefacto compilado de salida, y después de cada edición hay que extraer el código ("tangle") y colocarlo en su destino
- Puede automatizarse, pero es fácil que aparezca el problema de que, si un usuario o un agente edita el código real, este luego sea sobrescrito en el siguiente tangle
Patrones de uso antes de los agentes
- Hubo resultados suficientemente buenos al usar programación literaria para la gestión de configuraciones personales, por lo que la idea no se abandonó incluso antes de la aparición de los LLM
- Un patrón de uso de Org Mode para pruebas manuales y toma de notas: en lugar de la línea de comandos, se escriben y ejecutan comandos en el editor, se editan hasta que cada paso sea correcto y luego los resultados se guardan en su lugar
- "Si combinas la toma de notas con la ejecución de pruebas, las notas se generan gratis al terminar la prueba"
Un nuevo flujo de trabajo con agentes
- Los agentes de codificación como Claude y Kimi entienden muy bien la sintaxis de Org Mode, y como Org es un lenguaje de marcado permisivo, los LLM lo manejan especialmente bien
- La enorme sintaxis de Org Mode puede ser una desventaja para los humanos, pero no representa un problema para los modelos de lenguaje
- Si durante una prueba funcional se le pide al agente que escriba un runbook en Org, entonces:
- La explicación contiene la reflexión del modelo sobre la intención de cada paso
- Los bloques de código, tras ser revisados, pueden ejecutarse de forma interactiva uno por uno o completos como si fueran un script
- Los resultados se guardan debajo del código, como en un cuaderno Jupyter
- Se puede editar la explicación y pedirle al modelo que actualice el código, o editar el código y dejar que el modelo refleje su significado en la explicación, o permitir que el agente cambie ambos al mismo tiempo
- Así desaparece el problema de mantener narrativas paralelas
El trabajo clave que eliminan los agentes
- Si se deja en manos del agente el proceso de tangling, también se resuelve el problema de la extracción del código
- Con un archivo
AGENTS.md se le puede indicar al agente que trate los archivos Org como fuente de verdad, que siempre escriba explicaciones y que haga tangle antes de ejecutar
- El agente domina todas estas tareas y nunca se cansa de reescribir explicaciones después de modificar el código
- Los agentes eliminan el trabajo adicional fundamental que ha impedido el uso generalizado de la programación literaria, aprovechando además lo que los LLM mejor hacen: traducir y resumir
Beneficios esperados
- La base de código puede exportarse a varios formatos para que sea más cómoda de leer
- Esto es especialmente importante si el rol principal de los ingenieros está cambiando de escribir a leer
- Aunque no está respaldado por datos, se plantea que la calidad del código generado también podría mejorar, porque la narrativa que explica la intención de cada bloque aparece junto al código dentro del contexto
- Hasta ahora no se ha probado en una base de código grande y de producción; por ahora se usa en flujos de trabajo de pruebas y documentación de procesos manuales
Limitaciones de Org Mode y alternativas
- El formato Org está muy integrado con Emacs, lo que se vuelve un factor limitante, y se mantiene desde hace tiempo la convicción de que Org debería salir fuera de Emacs
- Dan ganas de recomendar Markdown como alternativa, pero Markdown carece de capacidades suficientes para incluir metadatos
- El concepto de Properties de Org Mode permite manipular documentos de forma programática con Emacs Lisp, y ahora los LLM incluso escriben en la sección de file variables funciones personalizadas en Emacs Lisp específicas para ese documento
- Markdown no tiene una función como los header arguments de Org Mode para especificar detalles de ejecución de los bloques de código, como dónde ejecutarlos o en qué máquina remota
- Lo emocionante no es la implementación concreta de Emacs, sino la idea en sí
La pregunta clave
- "¿Con agentes, puede volverse práctico tener una base de código grande que pueda leerse como una narrativa y donde una máquina incansable mantenga sincronizados los cambios de código y sus explicaciones?"
2 comentarios
Opiniones en Hacker News
Creo que la forma más simple es hacer que el propio LLM deje sus comentarios
Así, cuando vuelva a leer el código después, podrá apoyarse en sus propias anotaciones, funcionando como una especie de memoria de largo plazo just-in-time
En
<summary>pondría el resumen, en<remarks>las razones y el contexto, y en<params>las restricciones, minimizando los comentarios en líneaAsí, al revisar un PR, se puede ver directamente el proceso de razonamiento del LLM en
<remarks>, lo que facilita detectar dónde entendió algo distinto a la intenciónAl final contaminan su propio contexto con información inútil y empeoran su comprensión
Todavía está lejos del nivel de alfabetización (literacy) de un humano
Pero cuando el LLM vuelve a leer el mismo código, justo ese tipo de comentarios es donde se detiene, así que podrían ser información valiosa
Por eso este tipo de comentarios sirve para preservar esa memoria
Creo que los lenguajes de programación surgieron porque el lenguaje natural tiene ambigüedad
Por eso los comentarios en código también terminan siendo ambiguos, y como no se ejecutan, se vuelven obsoletos rápidamente
Siento que los LLM son buenos traduciendo código, pero convertir prompts en lenguaje natural a código sigue siendo difícil
El buen código debería expresar claramente la intención, y muchos comentarios pueden ser una señal de mala calidad de código
Pero el buen software también debería incluir buena documentación
La programación literaria consiste más en escribir centrado en la explicación que en los detalles de implementación
El código define de forma estrecha el “cómo”, pero el lenguaje natural puede expresar el “qué”, dejando espacio para que el LLM proponga un mejor método
Tiene que haber información redundante para poder detectar y corregir errores
Solo establecen reglas que reducen el grado de libertad en la interpretación
A veces una metáfora o cierta ambigüedad puede ser una expresión más adecuada
Si le das código de ejemplo y documentación como plantilla, se reducen las alucinaciones (hallucination)
Hay estudios que muestran que los comentarios con estilo de programación literaria ayudan a los humanos a entender mejor el código
Investigadores de Google probaron si un LLM podía actualizar este tipo de comentarios y si eso ayudaba a la comprensión humana
La conclusión fue que los comentarios a nivel de bloque que explican la intención son los más efectivos
(Referencia: artículo de arXiv de 2024 "Natural Language Outlines for Code")
Un fenómeno interesante reciente es que antes a la gente le daba flojera escribir README o documentos de arquitectura para humanos
pero si dices que es para un LLM, la gente se muestra mucho más dispuesta a hacerlo
Pero el LLM consulta la documentación en cada tarea, así que la motivación para documentar se vuelve mucho más fuerte
Mensajes de commit y registros como ADR quizá los humanos no los vean, pero el LLM sí los lee todos
Al final, esos hábitos también terminan ayudando a los nuevos integrantes humanos
que quienes aprendieron a hablar con computadoras pero no a hablar con personas terminaron más rezagados después de graduarse
Porque para que el código funcione no hace falta que la documentación sea correcta
Por eso muchas veces se siente mejor ir directo al código que a la documentación
Yo veo que una combinación de programación literaria ligera y lenguajes orientados a convenciones encaja bien en la era de los agentes
Son buenos los lenguajes como Go, con compilación rápida y guías de estilo claras
Si haces que el agente consulte la Google Go Style Guide al escribir código, salen resultados bastante buenos
(Referencia: anécdota relacionada con Rob Pike)
Como los LLM son modelos de lenguaje, vale la pena invertir en escritura clara
Sin llegar necesariamente a la programación literaria, sí importan los buenos nombres, docstrings, firmas de tipos y comentarios que expliquen el “por qué”
Al final, la clave es crear patrones de comunicación para humanos y LLM por igual
Son especialmente importantes los documentos que explican la estructura de alto nivel a nivel de archivo, directorio y proyecto
Pero como esos conceptos abarcan varios archivos, siempre está el problema de dónde escribirlos y cómo mantener la sincronización entre documentación y código
En los últimos 10 años he escrito casi todo mi código con un enfoque de programación literaria
Creé nbdev para gestionar juntos código, documentación y pruebas con base en notebooks
Últimamente hice una herramienta llamada Solveit con integración de LLM y la usamos en toda la empresa
(enlace a Solveit)
La programación literaria también es útil para tareas fuera de la programación
Estaría bien agregar una demo corta o capturas de pantalla
Es interesante la idea de usar LLM para detectar automáticamente desajustes entre comentarios y código
Con el tiempo, la documentación inevitablemente deja de coincidir con el código, así que poder detectarlo de forma automática tendría mucho valor
Incluso se podría hacer una startup con algo así
Los cambios empiezan con un PR de documentación y luego el desarrollador los refleja en el código
En la revisión, documentación y código se muestran lado a lado para validarlos
También estaría diseñado para permitir exploración de contexto mediante enlaces entre documentos
Ej.: GitHub gh-aw, Continue.dev
La estructura en pares entre código de pruebas y código de producción es útil, como la contabilidad por partida doble
Las pruebas explican la intención del código, y el código complementa el significado de las pruebas
Si en una revisión una parte resulta confusa, puedes mirar la otra
La desventaja es que aumenta la cantidad de código, pero la mejora en legibilidad lo compensa
Yo también escribí hace poco sobre codificación basada en intención, y conecta con esta discusión
(enlace al blog)
Es importante que el codebase pueda transformarse a distintos formatos fáciles de leer
En adelante, incluso quienes no vienen de carreras técnicas estarán más cerca del código, y incluir lenguaje natural ayudará mucho a su productividad y aprendizaje
Wikipedia - Programación literaria
> La programación literaria (literate programming) es una metodología de programación que, al programar, pone más énfasis en crear código fácil de entender para las personas que en producir código compilable por una computadora. En otras palabras, su objetivo es programar como si se estuviera redactando documentación para que las personas puedan verla y comprenderla. Como la meta es “hacer que la programación pueda leerse como si se leyera una obra literaria”, recibió el nombre de “programación literaria”.