Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

We should revisit literate programming in the agent era

silly.business

Post reply on HN
Print view View original

231–240 of 270 posts

Re: We should revisit literate programming in the agent era

#231

Post by eru »

necovek wrote: post #219
eru wrote: post #162

Earlier quoted context omitted.

> 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. Fo…

Not really. Launchpad.net does not have any public branches I could share atm as an example, but Bazaar (now breezy) allowed having a nested "merge commit": your trunk would have "flattened" merge commits ("Merge branch foo"), and under it you could easily get to each individual commit by a developer ("Prototype", "Add test"...). It would really be shown as a tree, but smartness was wven richer. This was made possibl…

I am not quite sure what you are describing here. Git's underlying commit graph is a DAG.

You can use different, custom merge-drivers (or whatever it's called) for Git to get the behaviour you describe here.

Re: We should revisit literate programming in the agent era

#232

Post by eru »

crazygringo wrote: post #207
1718627440 wrote: post #106

Earlier quoted context omitted.

I don't think this is enough to completely obsolete comments, but a good chunk of that information can be encoded in a VCS. It encodes all past approaches and also contains the reasoning and why not in annotation. You can also query this per line of your project.

But why would you ever put that into your VCS as opposed to code comments? The VCS history has to be actively pulled up and reading through it is a slog, and history becomes exceptionally difficult to retrace in certain kinds of refactoring. In contrast, code comments are exactly what you need and no more, you can't accidentally miss them, and you don't have to do extra work to find them. I have never understood the…

Both have their place. While I mostly agree with you, there's a clear example where git history is better: delete old or dead or unused code, rather than comment it out.

Re: We should revisit literate programming in the agent era

#233

Post by zdragnar »

palata wrote: post #184
zdragnar wrote: post #104

Earlier quoted context omitted.

In your example, the implementation matches the intention. That is not the same thing. bool isWeekday(number: Int) { return number % 2 == 0 } With this small change, all we have are questions: Is the name wrong, or the behavior? Is this a copy / paste error? Where is the specification that tells me which is right, the name or the body? Where are the tests located that should verify the expected behavior? Did the impl…

I would call your example "bad code". Do you disagree with that?

Not at all. I'm just pointing out that code does not intrinsically convey intent, only implementation.

To use a less trite example, I'd probably find some case where a word or name can have different meanings in different contexts, and how that can be confusing rather than clarifying without further documentation or knowledge of the problem space.

Really though, any bug in the code you write is a deviation between intent and implementation. That's why documentation can be a useful supplement to code. If you haven't, take a look at the underhanded C contests- there's some fantastically good old gems in there that demonstrate how a plain reading of the code may not convey intent correctly.

The winner of this contest might be a good example: https://www.underhanded-c.org/_page_id_26.html

Re: We should revisit literate programming in the agent era

#234

Post by astrange »

CharlieDigital wrote: post #222
astrange wrote: post #220

Earlier quoted context omitted.

Almost nothing in a Claude Code session has to do with "your prompt", it works for an hour afterwards and mostly talks to itself. I've noticed if you give it small corrections it will leave nonsensical comments referring to your small correction as if it's something everyone knows.

It has everything to do with your prompt and why Claude Code has a plan mode: because the quality of your planning, prompting, and inputs significantly affects the output. Your assertion, then, is that even a 1 sentence prompt is as good as a 5 section markdown spec with detailed coding style guidance and feature, by feature specification. This is simply not true; the detailed spec and guidance will always outperform…

No, I use plan mode and have several rounds of conversation with it, but lately I've been doing tasks where it does tons of independent research and finds complicated conclusions in an existing old codebase. I don't really feel like either of those count as "a prompt".

The plan mode is useful because if you do corrections during development mode it does that silly thing where it leaves comments referring to your corrections.

Re: We should revisit literate programming in the agent era

#235

Post by crazygringo »

palata wrote: post #229
crazygringo wrote: post #209

Earlier quoted context omitted.

> Lots of comments in code is a code smell. Yes, really. No, not really. It's actually a sign of devs who are helping future devs who will maintain and extend the code, so they can understand it faster. It's professionalism and respect. > If I see lots of comments in code, I'm gonna go looking for the intern who just put up their first PR. And I'm going to find them to say good job, keep it up! You're saving us time…

> It's professionalism and respect. If someone gives me code full of superfluous comments, I don't consider it professional. Sounds like an intern who felt the need to comment everything because ever single line seemed very complex to them.

Nobody said anything about "superfluous" comments.

I'm assuming "lots of comments" means lots of meaningful comments. As complex code often requires. Nobody's talking about `i++; // increment i` here.

Re: We should revisit literate programming in the agent era

#236

Post by 3371 »

CharlieDigital wrote: post #189

The easiest thing to do is to have the LLM leave its own comments. This has several benefits because the LLM is going to encounter its own comments when it passes this code again. > - Apply comments to code in all code paths and use idiomatic C# XML comments > - be brief, concise, to the point > - add details and explain "why"; document reasoning and chain of thought, related files, business context, key decisions. >…

Somehow made me think I should enforce a rule agents should sign their conment so it's identifiable at first glance

Re: We should revisit literate programming in the agent era

#237

Post by awesome_dude »

palata wrote: post #230
awesome_dude wrote: post #221

Earlier quoted context omitted.

A little bit of "Don't judge me" and a little bit of "I nearly fell into a trap here, and started writing O(log n) search, but realised that it was a waste of time and effort (and would actually slow things down) - so to save you from that trap here's a note"

The risk with that is that because it was not obvious to you does not necessarily mean it's not obvious to others. Over the years, I have seen many, many juniors wrapping simple CLI invocations in a script because they just learned about them and thought they weren't obvious. - clone_git_repo.sh - run_docker_container.sh I do agree that something actually tricky should be commented. But that's exceedingly rare.

I mean, the whole point of explicit being superior to implicit is because what's obvious to some isn't necessarily obvious to everyone.

Someone following me could look at it and go.. "well duh" and that's not going to hurt anyone, but if I didn't put that comment and someone refractometer, then we have someone redoing and then undoing, for no good reason.

There's that meme where people are told to update the number of hours wasted because people try to refactor some coffee and have to undo it because it doesn't work

Re: We should revisit literate programming in the agent era

#238

Post by ajkjk »

sarchertech wrote: post #227
ajkjk wrote: post #70

Earlier quoted context omitted.

true, but that just means that's the problem to solve. probably the ideal architecture isn't possible right now. But I sorta imagine that you could later on take the full transcript of that conversation and expect any LLM to implement more or less the same thing based on it, so that eventually it becomes a full 'spec'. And maybe there is a way to trim the parts out of it that are not needed... like to automatically p…

> But I sorta imagine that you could later on take the full transcript of that conversation and expect any LLM to implement more or less the same thing based on it Why would you think this though? There are an infinite number of programs that can satisfy any non-trivial spec. We have theoretical solutions to LLM non-determinism, we have no theoretical solutions to prompt instability especially when we can’t even meas…

yeah but all of the infinite programs are valid if they satisfy the spec (well, within reason). That's kinda the point. Implementation details like how the code is structured or what language it's in are swept under the rug, akin to how today you don't really care what register layout the compiler chooses for some code.

Re: We should revisit literate programming in the agent era

#239

Post by sarchertech »

ajkjk wrote: post #238
sarchertech wrote: post #227

Earlier quoted context omitted.

> But I sorta imagine that you could later on take the full transcript of that conversation and expect any LLM to implement more or less the same thing based on it Why would you think this though? There are an infinite number of programs that can satisfy any non-trivial spec. We have theoretical solutions to LLM non-determinism, we have no theoretical solutions to prompt instability especially when we can’t even meas…

yeah but all of the infinite programs are valid if they satisfy the spec (well, within reason). That's kinda the point. Implementation details like how the code is structured or what language it's in are swept under the rug, akin to how today you don't really care what register layout the compiler chooses for some code.

There has never been a non trivial program in the history of the world that could just “sweep all the implementation details under the rug”.

Compilers use rigorous modeling to guarantee semantic equality and that is only possible because they are translating between formal languages.

A natural language spec can never be precise enough to specify all possible observable behaviors, so your bot swarm trying to satisfy the spec is guaranteed to constantly change observable behaviors.

This gets exposed to users and churn, jank, and workflow breaking bugs.

Re: We should revisit literate programming in the agent era

#240

Post by necovek »

eru wrote: post #231
necovek wrote: post #219

Earlier quoted context omitted.

Not really. Launchpad.net does not have any public branches I could share atm as an example, but Bazaar (now breezy) allowed having a nested "merge commit": your trunk would have "flattened" merge commits ("Merge branch foo"), and under it you could easily get to each individual commit by a developer ("Prototype", "Add test"...). It would really be shown as a tree, but smartness was wven richer. This was made possibl…

I am not quite sure what you are describing here. Git's underlying commit graph is a DAG. You can use different, custom merge-drivers (or whatever it's called) for Git to get the behaviour you describe here.

Certainly, but merges are treated differently by default, and getting to this sort of output would require "custom" tooling for things like "git log".

Whereas bzr just did the expected thing.

Post reply on HN