Donald Knuth introduced literate programming in 1984 with a simple argument: software should be written primarily as a human-readable narrative, not just a set of machine instructions. Despite many attempts, the idea never fully stuck.
LLMs introduce a third audience: the coding agent. From experience, lack of documentation causes agents to hallucinate and make wrong assumptions. This got me thinking, how do you optimize code for all three readers at once?
This led me to build Explicode, an open-source modern take on literate programming focused on simplicity and flexibility. The core idea: enable Markdown inside code comment blocks. Comments are ignored at runtime, so the machine is unaffected. They live next to the code and version with Git, so agents always have full context. And they can be rendered into clean, rich documents for humans, including links, images, diagrams, and math. Currently, Explicode comes as a VS Code extension to preview docs live as you write in your IDE, no config required, and 15+ programming languages are supported. It also ships with an agent skill file to teach tools like Claude and Cursor to write Explicode-style comments automatically.
What do you think, is optimizing for agents a strong enough reason for literate programming to finally catch on? If you have time to check out the project, any feedback or contributions are hugely appreciated.
Donald Knuth introduced literate programming in 1984 with a simple argument: software should be written primarily as a human-readable narrative, not just a set of machine instructions. Despite many attempts, the idea never fully stuck.
LLMs introduce a third audience: the coding agent. From experience, lack of documentation causes agents to hallucinate and make wrong assumptions. This got me thinking, how do you optimize code for all three readers at once?
This led me to build Explicode, an open-source modern take on literate programming focused on simplicity and flexibility. The core idea: enable Markdown inside code comment blocks. Comments are ignored at runtime, so the machine is unaffected. They live next to the code and version with Git, so agents always have full context. And they can be rendered into clean, rich documents for humans, including links, images, diagrams, and math. Currently, Explicode comes as a VS Code extension to preview docs live as you write in your IDE, no config required, and 15+ programming languages are supported. It also ships with an agent skill file to teach tools like Claude and Cursor to write Explicode-style comments automatically.
What do you think, is optimizing for agents a strong enough reason for literate programming to finally catch on? If you have time to check out the project, any feedback or contributions are hugely appreciated.