We should revisit literate programming in the agent era
silly.business
We should revisit literate programming in the agent era
1–10 of 270 posts
Re: We should revisit literate programming in the agent era
#2> This is especially important if the primary role of engineers is shifting from writing to reading.
This was always the primary role. The only people who ever said it was about writing just wanted an easy sales pitch aimed at everyone else.
Literate programming failed to take off because with that much prose it inevitably misrepresents the actual code. Most normal comments are bad enough.
It's hard to maintain any writing that doesn't actually change the result. You can't "test" comments. The author doesn't even need to know why the code works to write comments that are convincing at first glance. If we want to read lies influenced by office politics, we already have the rest of the docs.
Re: We should revisit literate programming in the agent era
#3> This is especially important if the primary role of engineers is shifting from writing to reading. This was always the primary role. The only people who ever said it was about writing just wanted an easy sales pitch aimed at everyone else. Literate programming failed to take off because with that much prose it inevitably misrepresents the actual code. Most normal comments are bad enough. It's hard to maintain any w…
You're right that you can't test comments, but you can test the code they describe. That's what reproducibility bundles do in scientific computing ;; the prose says "we filtered variants with MAF < 0.01", and the bundle includes the exact shell command, environment, and checksums so anyone can verify the prose matches reality. The prose becomes a testable claim rather than a decorative comment. That said, I agree the failure mode of literate programming is prose that drifts from code. The question is whether agents reduce that drift enough to change the calculus.
Re: We should revisit literate programming in the agent era
#4> This is especially important if the primary role of engineers is shifting from writing to reading. This was always the primary role. The only people who ever said it was about writing just wanted an easy sales pitch aimed at everyone else. Literate programming failed to take off because with that much prose it inevitably misrepresents the actual code. Most normal comments are bad enough. It's hard to maintain any w…
I don't buy that. Writing is taking a bad rap from all this. Writing _is_ a form of more intense reading. Reading on steroids, as they say. If reading is considered good, writing should be considered better.
Re: We should revisit literate programming in the agent era
#5> This is especially important if the primary role of engineers is shifting from writing to reading. This was always the primary role. The only people who ever said it was about writing just wanted an easy sales pitch aimed at everyone else. Literate programming failed to take off because with that much prose it inevitably misrepresents the actual code. Most normal comments are bad enough. It's hard to maintain any w…
> You can't "test" comments.
I'm thinking that we're approaching a world where you can both test for comments and test the comments themselves.
Re: We should revisit literate programming in the agent era
#6> This is especially important if the primary role of engineers is shifting from writing to reading. This was always the primary role. The only people who ever said it was about writing just wanted an easy sales pitch aimed at everyone else. Literate programming failed to take off because with that much prose it inevitably misrepresents the actual code. Most normal comments are bad enough. It's hard to maintain any w…
I don't buy that. Writing is taking a bad rap from all this. Writing _is_ a form of more intense reading. Reading on steroids, as they say. If reading is considered good, writing should be considered better.
Writing in that draft style is really only useful because a) you read the results and b) you write an improved version at the end. Drafting forever is not considered "better" because someone (usually you) has to sift through the crap to find the good parts.
This is especially pronounced in the programming workplace, where the most "senior" programmers are asked to stop programming so they can review PRs.
Re: We should revisit literate programming in the agent era
#7Considering LLMs are models of language, investing in the clarity of the written word pays off in spades.
I don't know whether "literate programming" per se is required. Good names, docstrings, type signatures, strategic comments re: "why", a good README, and thoughtfully-designed abstractions are enough to establish a solid pattern.
Going full "literate programming" may not be necessary. I'd maybe reframe it as a focus on communication. Notebooks, examples, scripts and such can go a long way to reinforcing the patterns.
Ultimately that's what it's about: establishing patterns for both your human readers and your LLMs to follow.
Re: We should revisit literate programming in the agent era
#8I have noticed a trend recently that some practices (writing a decent README or architecture, being precise and unambiguous with language, providing context, literate programming) that were meant to help humans were not broadly adopted with the argument that it's too much effort. But when done to help an LLM instead of a human a lot of people suddenly seem to be a lot more motivated to put in the effort.
Re: We should revisit literate programming in the agent era
#9For me this is where a config layer shines. Develop a decent framework and then let the agents spin out the configuration.
This allows a trusted and tested abstraction layer that does not shift and makes maintenance easier, while making the code that the agents generate easier to review and it also uses much less tokens.
So as always, just build better abstractions.
Re: We should revisit literate programming in the agent era
#10but doesn't "the code is documentation" work better for machines?
and don't we have doc-blocks?