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

121–130 of 270 posts

Re: We should revisit literate programming in the agent era

#121

Post by musicale »

casey2 wrote: post #117
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…

Programming languages are natural and ambiguous too, what does READ mean? you have to look it up to see the types. The power comes from the fact that it's audit-able, but that you don't need to audit it every time you want to write some code. You think you write good code? try to prove it after the compiler gets through with it. Natural languages are richer in ideas, it may be harder to get working code going from a…

> Programming languages are natural and ambiguous too

Programming languages work because they are artificial (small, constrained, often based on algebraic and arithmetic expressions, boolean logic, etc.) and have generally well-defined semantics. This is what enables reliable compilers and interpreters to be constructed.

Re: We should revisit literate programming in the agent era

#123

Post by deathanatos »

bonesss wrote: post #120
AdieuToLogic wrote: post #100

Earlier quoted context omitted.

> Yes comments can lie ... Comments only lie if they are allowed to become one. Just like a method name can lie. Or a class name. Or ...

Right. The compiler ensures that the code is valid, and what ensures that ‘ // used a suboptimal sort because reasons ’ is updated during a global refactor that changes the method? … some dude living in that module all day every day exercising monk-like discipline? That is unwanted for a few reasons, notably the routine failures of such efforts over time. Module names and namespaces and function names can lie. But th…

> what ensures that ‘// used a suboptimal sort because reasons’ is updated during a global refactor that changes the method?

And for that matter, what ensures it is even correct the first time it is written?

(I think this is probably the far more common problem when I'm looking at a bug, newly discovered: the logic was broken on day 1, hasn't changed since; the comment, when there is one, is as wrong as the day it was written.)

Re: We should revisit literate programming in the agent era

#124

Post by pdntspa »

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…

> because my prompts are in natural languages, and hence ambiguous.

Legalese developed specifically because natural language was too ambiguous. A similar level of specificity for prompting works wonders

One of the issues with specifying directions to the computer with code is that you are very narrowly describing how something can be done. But sometimes I don't always know the best 'how', I just know what I know. With natural language prompting the AI can tap into its training knowledge and come up with better ways of doing things. It still needs lots of steering (usually) but a lot of times you can end up with a superior result.

Re: We should revisit literate programming in the agent era

#125

Post by 1718627440 »

eru wrote: post #119
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.

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.

Re: We should revisit literate programming in the agent era

#126

Post by hinkley »

analog31 wrote: post #103
hinkley wrote: post #28

Earlier quoted context omitted.

Paraphrasing an observation I stole many years ago: A bunch of us thought learning to talk to computers would get them out of learning to talk to humans and so they spent 4 of the most important years of emotional growth engaging in that, only to graduate and discover they are even farther behind everyone else in that area.

This raises an interesting point. I've speculated that if someone has a hard time expressing themselves to other humans verbally or in writing, they're also going to have a hard time writing human-readable code. The two things are rooted in the same basic abilities. Writing documentation or comments in the code at least gives someone two slim chances at understanding them, instead of just one. I have the opposite pro…

I think there’s some of that, but it’s also probably a thing where people who make good tutors/mentors tend to write clearer code as well, and the Venn diagram for that is a bit complicated.

Concise code is going to be difficult if you can’t distill a concept. And that’s more than just verbal intelligence. Though I’m not sure how you’d manage it with low verbal intelligence.

Re: We should revisit literate programming in the agent era

#127

Post by baq »

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…

Docs and code work together as mutually error correcting codes. You can’t have the benefits of error detection and correction without redundant information.

Re: We should revisit literate programming in the agent era

#128

Post by vnorilo »

pdntspa wrote: post #124
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…

> because my prompts are in natural languages, and hence ambiguous. Legalese developed specifically because natural language was too ambiguous. A similar level of specificity for prompting works wonders One of the issues with specifying directions to the computer with code is that you are very narrowly describing how something can be done. But sometimes I don't always know the best 'how', I just know what I know. Wit…

Yes. LLMs are search engines into the (latent) space or source code. Stuff you put into the context window is the "query". I've had some good results by minimizing the conversational aspect, and thinking in terms of shaping the context: asking the LLM to analyze relevant files, nor because I want the analysis, but because I want a good reading in the context. LLMs will work hard to stay in that "landscape", even with vague prompts. Often better than with weirdly specific or conflicting instructions.

Re: We should revisit literate programming in the agent era

#129

Post by necovek »

bottd wrote: post #56
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…

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

Having "grown up" on free software, I've always been quick to jump into code when documentation was dubious or lacking: there is only one canonical source of truth, and you need to be good at reading it.

Though I'd note two kinds of documentation: docs how software is built (seldom needed if you have good source code), and how it is operated. When it comes to the former, I jump into code even sooner as documentation rarely answers my questions.

Still, I do believe that literate programming is the best of both worlds, and I frequently lament the dead practice of doing "doctests" with Python (though I guess Jupyter notebooks are in a similar vein).

Usually, the automated tests are the best documentation you can have!

Re: We should revisit literate programming in the agent era

#130

Post by necovek »

AdieuToLogic wrote: post #99
bottd wrote: post #56

Earlier 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. An axiom I have long held regarding documenting code is: Code answers what it does, how it does it, when it is used, and who uses it. What it cannot answer is why it exists. Comments accomplish this.

Good naming and good tests can get you 90% of the way to "why" too.
Post reply on HN