I think we’re on the verge of readable code and human-edited code disappearing.
There is a paradigm shift coming. Ephemeral code.
We should revisit literate programming in the agent era
161–170 of 270 posts
Re: We should revisit literate programming in the agent era
#162Earlier quoted context omitted.
Git history is incredible important, yes, but also limited. Practically, it only encodes information that made it into `main`, not what an author just mulled over in their head or just had a brief prototype for, or ran an unrelated toy simulation over.
In fairness to GP, they said VCS, not Git, even if they are somewhat synonomous today. Other VCSes did support graph histories. Still, "3rd dimension" code reasoning (backwards in time) has never been merged well with code editing.
> Other VCSes did support graph histories.
Yes, git ain't the only one, but apart from interface difference, they are pretty much compatible in what they allow you to record in the history, I think?
Part of the problem here is that we use git for two only weakly correlated purposes:
- A history of the code
- Make nice and reviewable proposals for code changes ('Pull Request')
For the former, you want to be honest. For the latter, you want to present a polished 'lie'.
Re: We should revisit literate programming in the agent era
#163I'd much much rather the model write the code blocks than the prose myself. In my experience LLM can produce pretty decent code, but the writing is horrible. If anything I would prefer an agentic tool where you don't even see the slop. I definitely would rather it not be committed.
Re: We should revisit literate programming in the agent era
#164I think we’re on the verge of readable code and human-edited code disappearing. There is a paradigm shift coming. Ephemeral code.
Those two are not linked. I could buy that maybe human-readable code will be the minority.
But what does ephemeral code even means? That we will throw everything out of the window at every release cycle and recreate from scratch with llms based on specs? That's not happening
Re: We should revisit literate programming in the agent era
#165Earlier quoted context omitted.
Git history is incredible important, yes, but also limited. Practically, it only encodes information that made it into `main`, not what an author just mulled over in their head or just had a brief prototype for, or ran an unrelated toy simulation over.
If you throw away commit messages, that is on you, it is not a limitation of Git. If I am cleaning up before merging, I'm maybe rephrasing things, but I am not throwing that information away. I regularly push branches under 'draft/...' or 'fail/...' to the central project repository.
Sure, but you are still supposed to clean things up to make the life of the reviewer easier.
There's an inherent tension between honest history and a polished 'lie' to make the reviewer's life easier.
Re: We should revisit literate programming in the agent era
#166Earlier quoted context omitted.
Confusing code is one thing, but projects with more complex requirements or edge cases benefit from additional comments and documentation. Not everything is easily inferred from code or can be easily found in a large codebase. You can also describe e.g. chosen tradeoffs.
There's no way around just learning the codebase. I have never seen code documentation that was complete or correct, let alone both.
I have written code that was correct and necessarily written the way it was oly to have it repeatedly altered by well meaning colleagues who thought it looked wrong, inefficient, or unidiomatic. Eventually I had to fill it with warning comments and write a substantial essay explaining why it had to be the way it was,
Code tells you what is happening but it doesn't always do it so that it is easy to understand and it almost never tells you why something is the way it is.
Re: We should revisit literate programming in the agent era
#167Earlier quoted context omitted.
> If there is a need to comment the code all over the place, to me it means that the code is maybe not as good as it should be :-) If good code was enough on its own we would read the source instead of documentation. I believe part of good software is good documentation. The prose of literate source is aimed at documentation, not line-level comments about implementation.
> If good code was enough on its own we would read the source instead of documentation. Uh. We do. We, in fact, do this very thing. Lots of comments in code is a code smell. Yes, really. If I see lots of comments in code, I'm gonna go looking for the intern who just put up their first PR. > I believe part of good software is good documentation It is not. Docs tell you how to use the software. If you need to know what…
> If you need to know what it does, you read the code.
True.
But If you need to know why it does what its does, you read the comments. And often you need that knowledge if you are about to modify it.
Re: We should revisit literate programming in the agent era
#168Earlier quoted context omitted.
> If there is a need to comment the code all over the place, to me it means that the code is maybe not as good as it should be :-) If good code was enough on its own we would read the source instead of documentation. I believe part of good software is good documentation. The prose of literate source is aimed at documentation, not line-level comments about implementation.
> If good code was enough on its own we would read the source instead of documentation. That's 100% how I work -- reading the source. If the code is confusing, the code needs to be fixed.
Code alone can never describe intent or rationale.
Re: We should revisit literate programming in the agent era
#169Earlier quoted context omitted.
There's no way around just learning the codebase. I have never seen code documentation that was complete or correct, let alone both.
I have written code that was correct and necessarily written the way it was oly to have it repeatedly altered by well meaning colleagues who thought it looked wrong, inefficient, or unidiomatic. Eventually I had to fill it with warning comments and write a substantial essay explaining why it had to be the way it was, Code tells you what is happening but it doesn't always do it so that it is easy to understand and it…
Difficult to say without an example, but "code isn't enough" is just one possible conclusion in this case. Another one could be that the code is not actually as good as expected, and another one is that the colleagues may need to... do something about it.
An obvious example I have is CMake. I have seen so many people complaining about CMake being incomprehensible, refactoring it to make it terrible, even wrapping it in Makefiles (and then wrapping that in Dockerfiles). But the problem wasn't the original CMakeLists or a lack of comments in it. The problem was that those developers had absolutely no clue about how CMake works, and felt like they should spend a few hours modifying it instead of spending a few hours understanding it.
However, I do agree that sometimes there is a need for a comment because something is genuinely tricky. But that is rare enough that I call it "a comment" and not "literate programming".
Re: We should revisit literate programming in the agent era
#170I think we’re on the verge of readable code and human-edited code disappearing. There is a paradigm shift coming. Ephemeral code.
Those two are not linked. I could buy that maybe human-readable code will be the minority. But what does ephemeral code even means? That we will throw everything out of the window at every release cycle and recreate from scratch with llms based on specs? That's not happening
I think you're right, ephemeral code would be the concept that you have (I'm hand-waving) "the spec", that specifies what the code should be doing and the AI could regenerate the code any time based on it.
I'm also baffled by this concept and fundamentally believe that code _should be_ the ground truth (the spec), hence it should be human readable. That's what "clean code" would be about, choosing tools and abstractions so that code is consumable for humans and easy to reason about, debug and extend.
If we let go of that and rely on LLMs entirely... not sure where that would land, since computers ultimately execute the code - and the company is liable for the results of that code being executed -, not the plain language "specs".