We need an append-only programming language.
We should revisit literate programming in the agent era
31–40 of 270 posts
Re: We should revisit literate programming in the agent era
#32Interesting and semi-related idea: use LLMs to flag when comments/docs have come out of sync with the code.
The big problem with documentation is that if it was accurate when it was written, it's just a matter of time before it goes stale compared to the code it's documenting. And while compilers can tell you if your types and your implementation have come out of sync, before now there's been nothing automated that can check whether your comments are still telling the truth.
Somebody could make a startup out of this.
Re: We should revisit literate programming in the agent era
#33Interesting and semi-related idea: use LLMs to flag when comments/docs have come out of sync with the code. The big problem with documentation is that if it was accurate when it was written, it's just a matter of time before it goes stale compared to the code it's documenting. And while compilers can tell you if your types and your implementation have come out of sync, before now there's been nothing automated that c…
There is at least one startup doing it already (I'm not affiliated with it in any way):
https://promptless.ai/
Re: We should revisit literate programming in the agent era
#34[deleted]
Re: We should revisit literate programming in the agent era
#35Earlier quoted context omitted.
Yeah, I think what is needed is somewhere between docstrings+strategic comments, and literate programming. Basically, it's incredibly helpful to document the higher-level structure of the code, almost like extensive docstrings at the file level and subdirectory level and project level. The problem is that major architectural concepts and decisions are often cross-cutting across files and directories, so those aren't…
Also: "Bad programmers worry about the code. Good programmers worry about data structures and their relationships." -- Linus Torvalds
> "Bad programmers worry about the code. Good programmers worry about data structures and their relationships."
If you get the architecture wrong, everyone complains. If you get it right, nobody notices it's there.
Re: We should revisit literate programming in the agent era
#36>I don't have data to support this
With there being data that shows context files which explain code reduces the performance of them, it is not straightforward that literate programming is better so without data this article is useless.
Re: We should revisit literate programming in the agent era
#37Interesting and semi-related idea: use LLMs to flag when comments/docs have come out of sync with the code. The big problem with documentation is that if it was accurate when it was written, it's just a matter of time before it goes stale compared to the code it's documenting. And while compilers can tell you if your types and your implementation have come out of sync, before now there's been nothing automated that c…
If you have CI hooked up to AI you could you just use a SLM to do that in a periodic job with https://github.github.com/gh-aw/ or https://www.continue.dev/. You could also have it detect architectural drift.
Re: We should revisit literate programming in the agent era
#38Earlier quoted context omitted.
Also: "Bad programmers worry about the code. Good programmers worry about data structures and their relationships." -- Linus Torvalds
> "Bad programmers worry about the code. Good programmers worry about data structures and their relationships." If you get the architecture wrong, everyone complains. If you get it right, nobody notices it's there.
The SRE's Lament.
Re: We should revisit literate programming in the agent era
#39Interesting and semi-related idea: use LLMs to flag when comments/docs have come out of sync with the code. The big problem with documentation is that if it was accurate when it was written, it's just a matter of time before it goes stale compared to the code it's documenting. And while compilers can tell you if your types and your implementation have come out of sync, before now there's been nothing automated that c…
I once had a mad idea of creating an automated documentation-driven paradigm where every directory/module/class/function has to have a DocString/JSDoc, with the higher level ones (directory/module) essentially being the documentation of features and architecture.
A ticket starts by someone opening a PR with suggested changes to the docs, the idea being that a non-technical person like a PM or tester could do it. The PR then passes to a dev who changes the code to match the doc changes.
Before merging, the tool shows the doc next to every modified piece of code and the reviewer must explicitly check a box to say it's still valid.
And docstrings would be able to link to other docstrings, so you could find out what other bits of code are connected to what you're working on (as that link doesn't always exist in code, e.g. across APIs) and read their docs to find the larger context and gotchas.
Re: We should revisit literate programming in the agent era
#40Interesting and semi-related idea: use LLMs to flag when comments/docs have come out of sync with the code. The big problem with documentation is that if it was accurate when it was written, it's just a matter of time before it goes stale compared to the code it's documenting. And while compilers can tell you if your types and your implementation have come out of sync, before now there's been nothing automated that c…
I'm a technical writer. Off the top of my head I reckon at least 10 startups have … started up … in this space since 2023.