We should revisit literate programming in the agent era
This post re-examines the long-debated concept of literate programming, proposing that AI agents could finally overcome its historical hurdle of prose-code synchronization. Hacker News reflects on whether AI genuinely solves this maintenance burden, or if it merely shifts priorities for what constitutes "good documentation" in a world increasingly assisted by large language models. The discussion touches upon the fundamental role of engineers, questioning if their task is truly shifting from writing to reading.
The Lowdown
The author champions a reconsideration of literate programming (LP) in the age of AI agents, arguing that artificial intelligence can overcome the practical difficulties that have historically hindered its adoption. LP, which aims to intersperse code with prose for narrative understanding, has traditionally struggled due to the overhead of keeping code and explanation synchronized.
- Historical Context: Literate programming has seen limited, niche adoption, notably in Jupyter notebooks for data science and Emacs Org Mode for polyglot programming.
- The AI Agent Solution: The core proposal is that LLMs can tirelessly maintain consistency between code and prose. Agents can be instructed to update prose when code changes, or vice-versa, and manage code extraction (tangling).
- Benefits: This integration could make large codebases readable like narratives and potentially improve generated code quality by providing in-context intent.
- Current Application: While not yet tested on large projects, the author finds success using this workflow for testing and documenting manual processes.
- Tool Agnosticism: The author emphasizes the idea of AI-assisted literate programming over specific tools like Emacs Org Mode, suggesting a more flexible format like Markdown would be ideal if it supported metadata.
The article concludes by posing the compelling question of whether AI agents can finally make large, narratively-structured codebases a practical reality, with prose kept in sync by tireless machines.
The Gossip
Prose Peril and AI Promises
Commenters debate the historical failure of literate programming, primarily citing the inevitable drift between prose and code and the difficulty of "testing" documentation. While some express skepticism that AI can truly resolve this fundamental issue, others are more optimistic, suggesting that future tools might even allow for the testing of comments themselves, or that AI agents could significantly reduce the drift.
Documentation Dynamics and Engineer's Evolving Role
The discussion extends to the broader topic of effective documentation, with some arguing that traditional methods like good names, docstrings, and READMEs are sufficient, questioning the necessity of full literate programming. A notable observation is made about a perceived shift in motivation: people seem more willing to put effort into documentation when it benefits an LLM compared to when it's solely for human readers. There's also a philosophical debate on whether an engineer's primary role is truly shifting from writing code to reading it, or if reading has always been the more critical aspect.