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

221–230 of 270 posts

Re: We should revisit literate programming in the agent era

#221

Post by awesome_dude »

palata wrote: post #181
awesome_dude wrote: post #68

Earlier quoted context omitted.

> Natural languages are ambiguous. That's the reason why we created programming languages. So the documentation around the code is generally ambiguous as well. Worse: it's not being executed, so it can get out of date (sometimes in subtle ways). I loathe this take. I have rocked up to codebases where there were specific rules banning comments because of this attitude. Yes comments can lie, yes there are no guards ens…

IMHO, you shouldn't have to justify yourself ("yeah yeah, this is not optimal, I know it because I am not an idiot"). Just write your code in O(n) if that's good enough now. Later, a developer may see that it needs to be optimised, and they should assume that the previous developer was not an idiot and that it was fine with O(n), but now it's not anymore. Or do you think that your example comment brings knowledge oth…

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"

Re: We should revisit literate programming in the agent era

#222

Post by CharlieDigital »

astrange wrote: post #220
CharlieDigital wrote: post #217

Earlier quoted context omitted.

The output of an LLM is a reflection of the input and instructions. If you have silly and verbose comments, then consider improving your prompt.

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 the 1 sentence prompt.

Re: We should revisit literate programming in the agent era

#224

Post by dinfinity »

palata wrote: post #171
actionfromafar wrote: post #159

Earlier quoted context omitted.

But the documentation can really help in telling why we are doing things. That also seeps in to naming things like classes. If that were not so, we'd just name everything Class1, Class2, Method1, Method2 and so on.

My point is that if your code is well written, it is self-documenting. Obviously Class1 and var2 are not self-documenting.

The code is what it does. The comments should contain what it's supposed to do.

Even if you give them equal roles, self-documenting code versus commented code is like having data on one disk versus having data in a RAID array.

Remember: Redundancy is a feature. Mismatches are information. Consider this:

// Calculate the sum of one and one

sum = 1 + 2;

You don't have to know anything else to see that something is wrong here. It could be that the comment is outdated, which has no direct effects and is easily solved. It could be that this is a bug in the code. In any case it is information and a great starting point for looking into a possible problem (with a simple git blame). Again, without needing any context, knowledge of the project or external documentation.

My take on developers arguing for self-documenting code is that they are undisciplined or do not use their tools well. The arguments against copious inline comments are "but people don't update them" and "I can see less of the code".

Re: We should revisit literate programming in the agent era

#225

Post by psychoslave »

palata wrote: post #53

I am not convinced. - Natural languages are ambiguous. That's the reason why we created programming languages. So the documentation around the code is generally ambiguous as well. Worse: it's not being executed, so it can get out of date (sometimes in subtle ways). - LLMs are trained on tons of source code, which is arguably a smaller space than natural languages. My experience is that LLMs are really good at e.g. tr…

>Natural languages are ambiguous. That's the reason why we created programming languages.

Programming languages can be ambiguous too. The thing with formal languages is more that they put a stricter and narrower interpretation freedom as a convention where it's used. If anything there are a subset of human expression space. Sometime they are the best tool for the job. Sometime a metaphor is more apt. Sometime you need some humour. Sometime you better stay in ambiguity to play the game at its finest.

Re: We should revisit literate programming in the agent era

#226

Post by ChicagoDave »

monsieurbanana wrote: post #164
ChicagoDave wrote: post #161

I 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

By ephemeral I mean we no longer care about code as an asset. If a feature is broken or requires changes, we can perform a clean organ transplant. The actual code doesn’t matter anymore. Its testable functionality is what matters.

Re: We should revisit literate programming in the agent era

#227

Post by sarchertech »

ajkjk wrote: post #70
Copyrightest wrote: post #62

Earlier quoted context omitted.

One problem with this is that there isn't really a "current prompt" that completely describes the current source code; each source file is accompanied by a full chat log, including false starts and misunderstandings. It's sort of like reading a git history instead of the actual file.

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 measure what correct is.

Re: We should revisit literate programming in the agent era

#228

Post by palata »

crazygringo wrote: post #210
Verdex wrote: post #205

Earlier quoted context omitted.

Clearly. Crazy thing. Number of times reading the source saved time and clarified why: many. Number of times reading the documentation saved time and clarified why: never. Perhaps I've just been unlucky? EDIT: The hilarious part to me is that everyone can talk past each other all day (reading the documentation) or we can show each other examples of good/bad documentation or good/bad code (reading the code) and unders…

> Number of times reading the documentation saved time and clarified why: never. OK, so let's use an example... if you need to e.g. make a quick plot with Matplotlib. You just... what? Block off a couple weeks and read the source code start to finish? Or maybe reduce it to just a couple days, if you're trying to locate and understand the code just for the one type of plot you're trying to create? And the several func…

Literate programming is not about documenting the public API, it's about documenting the implementation details, right? Otherwise no need for a new name, it's just "API documentation".

> if you need to e.g. make a quick plot with Matplotlib. You just... what?

Read the API documentation.

Now if you need to fix a bug in Matplotlib, or contribute a feature to it, then you read the code.

Re: We should revisit literate programming in the agent era

#229

Post by palata »

crazygringo wrote: post #209
habinero wrote: post #136

Earlier quoted context omitted.

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

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

Re: We should revisit literate programming in the agent era

#230

Post by palata »

awesome_dude wrote: post #221
palata wrote: post #181

Earlier quoted context omitted.

IMHO, you shouldn't have to justify yourself ("yeah yeah, this is not optimal, I know it because I am not an idiot"). Just write your code in O(n) if that's good enough now. Later, a developer may see that it needs to be optimised, and they should assume that the previous developer was not an idiot and that it was fine with O(n), but now it's not anymore. Or do you think that your example comment brings knowledge oth…

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.

Post reply on HN