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

171–180 of 270 posts

Re: We should revisit literate programming in the agent era

#171

Post by palata »

actionfromafar wrote: post #159
habinero wrote: post #138

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

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.

Re: We should revisit literate programming in the agent era

#172

Post by macey »

I agree it's worth revisiting. Actually I wrote about this recently, I didn't realise there was a precedent here. https://tessl.io/blog/how-to-capture-intent-with-coding-agen...

> As a benefit, the code base can now be exported into many formats for comfortable reading. This is especially important if the primary role of engineers is shifting from writing to reading.

Underrated point. Also, whether we like it or not, people without engineering backgrounds will be closer to code in the future. That trend isn't slowing down. The inclusion of natural language will make it easier for them to be productive and learn.

Re: We should revisit literate programming in the agent era

#173

Post by palata »

necovek wrote: post #130
AdieuToLogic wrote: post #99

Earlier quoted context omitted.

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

Agreed. Tests are documentation too. Tests are the "contract": "my code solves those issues. If you have to modify my tests, you have a different understanding than I had and should make sure it is what you want".

Re: We should revisit literate programming in the agent era

#174

Post by TuxSH »

samplifier wrote: post #160
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.

def reallyDumbIdeaByManagerWorkaroundMethodToGetCoverageToNinetyPercent(self): """Dont worry, this is a clear description of the method. """ return False

You exaggerate, but in this situation, I think putting a link to a Jira ticket or Slack convo (or whatever) as comment is best

Re: We should revisit literate programming in the agent era

#176

Post by palata »

ninalanyon wrote: post #167
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…

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

Do you have an example of such knowledge that you need to get from the comments? I have been programming for 20 years, and I genuinely don't see that much code that is so complex that it needs comments.

Not that it doesn't exist; sometimes it's needed. But so rarely that I call it "comments", and not a whole discipline in itself that is apparently be called "literate programming". Literate programming sounds like "you need to comment pretty much everything because code is generally hard to understand". I disagree with that. Most code is trivial, though you may need to learn about the domain.

Re: We should revisit literate programming in the agent era

#177

Post by vnorilo »

ptx wrote: post #152
vnorilo wrote: post #128

Earlier quoted context omitted.

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…

But search engines are not a good interface when you already know what you want and need to specify it exactly. See for example the new Windows start menu compared to the old-school run dialog – if I directly run "notepad", then I get always Notepad; but if I search for "notepad" then, after quite a bit of chugging and loading and layout shifting, I might get Notepad or I might get something from Bing or something en…

Indeed, which is not all that different from LLM code generation, to be honest.

Re: We should revisit literate programming in the agent era

#178

Post by mexicocitinluez »

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, what does READ mean?

Not nearly in the same sense actual language is ambiguous.

And ambiguity in programming is usually a bad thing, whereas in language it can usually be intended.

Good code, whatever that means, can read like a book. Event-driven architectures is a good example because the context of how something came to be is right in the event name itself.

Re: We should revisit literate programming in the agent era

#179

Post by mexicocitinluez »

musicale wrote: post #121
casey2 wrote: post #117

Earlier quoted context omitted.

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.

Exactly. Programming is the art of removing ambiguity and making it formal. And it's why the timelines between getting an EXACT plan of what I need to implement vs hazy requirements are so out of whack.

Re: We should revisit literate programming in the agent era

#180

Post by ithkuil »

dkersten wrote: post #168
wvenable wrote: post #109

Earlier quoted context omitted.

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

Indeed, you need both!

But documentation should not go too deep in the "how" otherwise it risks telling a lie after a while as the code changes but the documentation lags.

Post reply on HN