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

101–110 of 270 posts

Re: We should revisit literate programming in the agent era

#101

Post by what »

rustybolt wrote: post #8

I have noticed a trend recently that some practices (writing a decent README or architecture, being precise and unambiguous with language, providing context, literate programming) that were meant to help humans were not broadly adopted with the argument that it's too much effort. But when done to help an LLM instead of a human a lot of people suddenly seem to be a lot more motivated to put in the effort.

The difference is that they’re using the LLM to write those readmes and architecture and whatever else documents. They’re not putting any effort in.

Re: We should revisit literate programming in the agent era

#102

Post by eru »

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.

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.

Re: We should revisit literate programming in the agent era

#103

Post by analog31 »

hinkley wrote: post #28
rustybolt wrote: post #8

I have noticed a trend recently that some practices (writing a decent README or architecture, being precise and unambiguous with language, providing context, literate programming) that were meant to help humans were not broadly adopted with the argument that it's too much effort. But when done to help an LLM instead of a human a lot of people suddenly seem to be a lot more motivated to put in the effort.

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 problem. Granted, I'm not a software developer, but only use code as a problem solving tool. But once again, adding comments to my code gives me two slim chances of understanding it later, instead of one.

Re: We should revisit literate programming in the agent era

#104

Post by zdragnar »

palata wrote: post #51
zdragnar wrote: post #13

Earlier quoted context omitted.

Code doesn't express intent, only the implementation. Docblocks are fine for specifying local behavior, but are terrible for big picture things.

Well many times it does. bool isEven(number: Int) { return number % 2 == 0 } I would say this expresses the intent, no need for a comment saying "check if the number is even". Most of the code I read (at work) is not documented, still I understand the intent. In open source projects, I used to go read the source code because the documentation is inexistent or out-of-date. To the point where now I actually go directly…

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 implementation initially match the intent, but some business rule changed that necessitated a change to the implantation and the maintainer didn't bother to update the name?

Both of our examples are rather trite- I agree that I wouldn't bother documenting the local behavior of an "isEven" function. I probably would want a bit of documentation at the callsite stating why the evenness of a given number is useful to know. Generally speaking, this is why I tend to dislike docblock style comments and prefer bigger picture documentation instead- because it better captures intent.

Re: We should revisit literate programming in the agent era

#105

Post by larusso »

awesome_dude wrote: post #68
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. 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…

I don’t disagree here. I personally like to put the why into commit messages though. It’s my longtime fight to make people write better commit messages. Most devs I see describe what they did. And in most cases that is visible from the change-set. One has to be careful here as similar to line documentation etc everything changes with size. But I prefer if the why isn’t sprinkled between source. But I’m not dogmatic about it. It really depends.

Re: We should revisit literate programming in the agent era

#106

Post by 1718627440 »

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

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.

Re: We should revisit literate programming in the agent era

#107

Post by AdieuToLogic »

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

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.

> But it's even harder for code to answer the 'why not' question.

Great point. Well-placed documentation as to why an approach was not taken can be quite valuable.

For example, documenting that domain events are persisted in the same DB transaction as changes to corresponding entities and then picked up by a different workflow instead of being sent immediately after a commit.

Re: We should revisit literate programming in the agent era

#108

Post by 1718627440 »

zdragnar wrote: post #12
rustybolt wrote: post #8

I have noticed a trend recently that some practices (writing a decent README or architecture, being precise and unambiguous with language, providing context, literate programming) that were meant to help humans were not broadly adopted with the argument that it's too much effort. But when done to help an LLM instead of a human a lot of people suddenly seem to be a lot more motivated to put in the effort.

In my years of programming, I find that humans rarely give documentation more than a cursory glance up until they have specific questions. Then they ask another person if one is available rather than read for the answer. The biggest problem is that humans don't need the documentation until they do. I recall one project that extensively used docblock style comments. You could open any file in the project and find at l…

I think this really depends on culture. If you target OS APIs or the libc, the documentation is stellar. You have several standards and then conceptual documentation and information about particular methods all with historic and current and implementation notes, then there is also an interactive hypertext system. I solve 80% of my questions with just looking at the official documentation, which is also installed on my computer. For the remaining I often try to use the WWW, but these are often so specific, that it is more successful to just read the code.

Once I step out of that ecosystem, I wonder how people even cope with the lack of good documentation.

Re: We should revisit literate programming in the agent era

#109

Post by wvenable »

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.

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

Re: We should revisit literate programming in the agent era

#110

Post by 1718627440 »

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

Post reply on HN