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

201–210 of 270 posts

Re: We should revisit literate programming in the agent era

#201

Post by empath75 »

trixn86 wrote: post #198

I don't think that agents actually benefit from comments that describe what the code does at all. In my experience in the best case they don't really improve response quality and in the worst case they drastically reduce it. This is just noise that does not help the AI understand the context any better. This has already been true for a trained developer and it is even more so true for AI agents. Natural language is i…

You can have perfectly good code, which is perfectly easy to understand which nevertheless _does not do what you intended to do_. That is why tests exist, after all.

Re: We should revisit literate programming in the agent era

#202

Post by ninalanyon »

palata wrote: post #176
ninalanyon wrote: post #167

Earlier quoted context omitted.

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

I've never properly tried literate programming, overkill for hobby projects and not practical for a team unless everyone agrees.

Examples of code that needs comments in my career tend to come from projects that model the behaviour of electrical machines. The longest running such project was a large object oriented model (one of the few places where OOP really makes sense). The calculations were extremely time consuming and there were places where we were operating with small differences between large numbers.

As team members came and went and as the project matured the team changed from one composed of electrical engineers, physicists, and mathematicians who knew the domain inside out to one where the bulk of the programmers were young computer science graduates who generally had no physical science background at all.

This meant that they often had no idea what the various parts of the program were doing and had no intuition that would make them stop and think or ask a question before fixing a bug in wat seemed the most efficient way.

The problem in this case is that sometimes you have to sacrifice runtime speed for correctness and numerical stability. You can't always re-order operations to reduce the number of assignments say and expect to get the same answers.

Of course you can write unit and functional tests to catch some such errors but my experience says that tests need even better comments than the code that is being tested.

Re: We should revisit literate programming in the agent era

#203

Post by JamesSwift »

solarkraft wrote: post #190
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. >…

How do you deal with the comments sometimes being relatively noisy for humans? I tend to be annoyed by comments overly referring to a past correction prompt and not really making sense by themselves, but then again this IS probably the highest value information because these are exactly the things the LLM will stumble on again.

I really hate its tendency to leave those comments as well. I seem to have coached it out with some claude.md instructions but they still happen on occasion.

Re: We should revisit literate programming in the agent era

#204

Post by crazygringo »

Verdex wrote: post #199
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.

I do read the code instead of the documentation, whenever that is an option. Interesting factiod. The number of times I've found the code to describe what the software does more accurately than the documentation: many. The number of times I've found the documentation to describe what the software does more accurately than the code: never.

You seem to misunderstand the purpose of documentation.

It's not to be more accurate than the code itself. That would be absurd, and is by definition impossible, of course.

It's to save you time and clarify why's. Hopefully, reading the documentation is about 100x faster than reading the code. And explains what things are for, as opposed to just what they are.

Re: We should revisit literate programming in the agent era

#205

Post by Verdex »

crazygringo wrote: post #204
Verdex wrote: post #199

Earlier quoted context omitted.

I do read the code instead of the documentation, whenever that is an option. Interesting factiod. The number of times I've found the code to describe what the software does more accurately than the documentation: many. The number of times I've found the documentation to describe what the software does more accurately than the code: never.

You seem to misunderstand the purpose of documentation. It's not to be more accurate than the code itself. That would be absurd, and is by definition impossible, of course. It's to save you time and clarify why's . Hopefully, reading the documentation is about 100x faster than reading the code. And explains what things are for , as opposed to just what they are.

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

Re: We should revisit literate programming in the agent era

#206

Post by analog31 »

1718627440 wrote: post #110
analog31 wrote: post #103

Earlier quoted context omitted.

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've speculated that if someone has a hard time expressing themselves to other humans verbally or in writing I don't think they have actually problems with expressing themselves, code is also just a language with a very formal grammar and if you use that approach to structure your prose, it's also understandable. The struggle is more to mentally encode non-technical domain knowledge, like office politics or emotion…

That's true. But people have had formal language for millennia, so why don't we use it?

Here's my hunch. Formal specifiation is so inefficient that cynics suspect it of being a form of obstructionism, while pragmatic people realize that they can solve a problem themselves, quicker than they can specify their requirements.

Re: We should revisit literate programming in the agent era

#207

Post by crazygringo »

1718627440 wrote: post #106
eru wrote: post #102

Earlier quoted context omitted.

An important addendum: code can sometimes, with a bit of extra thinking of part of the reader, answer the 'why' question. But it's even harder for code to answer the 'why not' question. Ie what were other approaches that we tried and that didn't work? Or what business requirements preclude these other approaches.

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 idea of relying on code history instead of code comments. It seems like it's all downsides, zero upsides.

Re: We should revisit literate programming in the agent era

#208

Post by palata »

tonyedgecombe wrote: post #193
palata wrote: post #169

Earlier quoted context omitted.

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…

I always think the biggest mistake is using CMake in the first place. I’ve never come across a project as convoluted and poorly documented as it.

What do you mean by "poorly documented"? I have been using it for 20 years, I have yet to find something that is not documented.

As for convoluted, I don't find it harder than the other build systems I use.

Really the problem I have with CMake is the amount of terribly-written CMakeLists. The norm seems to be to not know the basics of CMake but to still write a mess and then complain about CMake. If people wrote C the way they write CMake, we wouldn't blame the language.

Re: We should revisit literate programming in the agent era

#209

Post by crazygringo »

habinero wrote: post #136
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. 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 and money in the future.

Re: We should revisit literate programming in the agent era

#210

Post by crazygringo »

Verdex wrote: post #205
crazygringo wrote: post #204

Earlier quoted context omitted.

You seem to misunderstand the purpose of documentation. It's not to be more accurate than the code itself. That would be absurd, and is by definition impossible, of course. It's to save you time and clarify why's . Hopefully, reading the documentation is about 100x faster than reading the code. And explains what things are for , as opposed to just what they are.

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 function calls you need to set it up and display it in the end?

Instead of looking at the docs and figuring out how to do it in 5 or 10 min?

Because I am genuinely baffled here.

Post reply on HN