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

251–260 of 270 posts

Re: We should revisit literate programming in the agent era

#251

Post by 1718627440 »

analog31 wrote: post #206
1718627440 wrote: post #110

Earlier quoted context omitted.

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

> But people have had formal language for millennia, so why don't we use it?

In case you don't refer to the mathematical notion of formal, then we use formal language all the time. Every subject has its formal terms, contracts are all written in a formal way, specifications use formal language. Anything that really matters or is read by a large audience is written in formal language.

Re: We should revisit literate programming in the agent era

#252

Post by dinfinity »

palata wrote: post #246
dinfinity wrote: post #224

Earlier quoted context omitted.

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

> Redundancy is a feature. Mismatches are information. Consider this: Respectfully, if someone wrote code like this, I wouldn't want to work with them. I mean next step is "I copy paste code instead of writing functions, and in the comment above I mention all the other copies, so that it's easy to check that they are all doing the same thing redundantly". > The arguments against copious inline comments are "but peopl…

You did not engage with my main arguments. You should still do so.

1. Redundancy: "The code is what it does. The comments should contain what it's supposed to do. [...] You don't have to know anything else to see that something is wrong here." and specifically the concrete trivial (but effective) example.

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

> Respectfully, if someone wrote code like this, I wouldn't want to work with them. I mean next step is "I copy paste code [...]

This is an nonsensical slippery slope fallacy. In no way does that behavior follow from placing many comments in code. It also says nothing about the clearly demonstrated value of redundancy.

> I have been navigating code for 20 years and in good codebases, comments are rare and describe something "surprising".

Your definition of good here is circular. No argument on why they are good codebases. Did you measure how easy they were to maintain? How easy it was to onboard new developers? How many bugs it contained? Note also that correlation != causation: it might very well be that the good codebases you encountered were solo-projects by highly capable motivated developers and the comment-rich ones were complicated multi-developer projects with lots of developer churn.

> My problem with "literate programming" [...] is that I find it hard to trust developers who genuinely cannot understand unsurprising code without comments.

This is gatekeeping code by making it less understandable and essentially an admission that code with comments is easier to understand. I see the logic of this, but it is solving a problem in the wrong place. Developer competence should not be ascertained by intentionally making the code worse.

Re: We should revisit literate programming in the agent era

#253

Post by palata »

awesome_dude wrote: post #237
palata wrote: post #230

Earlier quoted context omitted.

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.

I mean, the whole point of explicit being superior to implicit is because what's obvious to some isn't necessarily obvious to everyone. Someone following me could look at it and go.. "well duh" and that's not going to hurt anyone, but if I didn't put that comment and someone refractometer, then we have someone redoing and then undoing, for no good reason. There's that meme where people are told to update the number o…

Do you write a comment before every for loop to explain how a for loop works? Do you write a comment above that to remind the reader that the next few lines are written in, say, Go, just like in the rest of the file? Do you write a comment explaining that the text appearing on the screen is actually digital and will disappear when you turn off the computer?

Obviously you don't, because you assume that the person reading that code has some level of knowledge. You don't say "well, it may not be obvious to everybody, so I need to explain everything".

I guess where we differ is that to me, a professional software developer should be able to understand good code. If they aren't, they are a junior who needs practice. But I am for designing tools for the professionals, not for the apprentices. The goal of an apprentice is to become a professional, not to remain an apprentice forever.

Re: We should revisit literate programming in the agent era

#254

Post by palata »

crazygringo wrote: post #235
palata wrote: post #229

Earlier quoted context omitted.

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

Nobody said anything about "superfluous" comments. I'm assuming "lots of comments" means lots of meaningful comments. As complex code often requires. Nobody's talking about `i++; // increment i` here.

> I'm assuming "lots of comments" means lots of meaningful comments.

That's not what literate programming is. Literate programming says that you explain everything in a natural language.

IMO, good code is largely unsurprising. I don't need comments for unsurprising code. I need comments for surprising code, but that is the exception, not the rule. Literate programming says that it is the rule, and I disagree.

Re: We should revisit literate programming in the agent era

#255

Post by palata »

dinfinity wrote: post #252
palata wrote: post #246

Earlier quoted context omitted.

> Redundancy is a feature. Mismatches are information. Consider this: Respectfully, if someone wrote code like this, I wouldn't want to work with them. I mean next step is "I copy paste code instead of writing functions, and in the comment above I mention all the other copies, so that it's easy to check that they are all doing the same thing redundantly". > The arguments against copious inline comments are "but peopl…

You did not engage with my main arguments. You should still do so. 1. Redundancy: "The code is what it does. The comments should contain what it's supposed to do. [...] You don't have to know anything else to see that something is wrong here." and specifically the concrete trivial (but effective) example. 2. "My take on developers arguing for self-documenting code is that they are undisciplined or do not use their to…

You talk as if you had scientific proof that literate programming is objectively better, and I was the weirdo contradicting it without bringing any scientific proof.

Fact is, you don't have any proof at all, you just have your intuition and experience. And I have mine.

> It also says nothing about the clearly demonstrated value of redundancy.

Clearly demonstrated, as in your example of "Calculate the sum of one and one"? I wouldn't call that a clear demonstration.

> This is gatekeeping code by making it less understandable

I don't feel like I am making it less understandable. My opinion is that a professional worker should have the required level of competence (otherwise they are not a professional in that field). In software engineering, we feed code to a compiler, and we trust that the compiler makes sure that the machine executes the code we write. The role of the software engineer is to understand that code.

Literate programming essentially says "I am incapable of writing code that is understandable, ever, so I always need to explain it in a natural language". Or "I am incapable of reading code, so I need it explained in a natural language". My experience is that good code is readable by competent software engineers without explaining everything. But not only that: code is more readable when it is more concise and not littered with comments.

> and essentially an admission that code with comments is easier to understand.

I disagree again. Code with comment is easier to understand for the people who cannot understand it without the comments. Now the question is, again: are those people competent to handle code professionally? Because if they don't understand the code without comments, many times they will just have to trust the comments. If they used the comments to actually understand the code, pretty quickly they would be competent enough to not require the comments. Which means that at the point where they need it, they are not yet professionals, but rather apprentices.

Re: We should revisit literate programming in the agent era

#256

Post by crazygringo »

palata wrote: post #254
crazygringo wrote: post #235

Earlier quoted context omitted.

Nobody said anything about "superfluous" comments. I'm assuming "lots of comments" means lots of meaningful comments. As complex code often requires. Nobody's talking about `i++; // increment i` here.

> I'm assuming "lots of comments" means lots of meaningful comments. That's not what literate programming is. Literate programming says that you explain everything in a natural language. IMO, good code is largely unsurprising. I don't need comments for unsurprising code. I need comments for surprising code, but that is the exception, not the rule. Literate programming says that it is the rule, and I disagree.

> Literate programming says that you explain everything in a natural language.

At a high level. Not line-by-line comments.

> IMO, good code is largely unsurprising. I don't need comments for unsurprising code.

I've never heard anything like that, and could not disagree more. Twenty different considerations might go into a single line of code. Often, one of them is something non-obvious. So you comment that thing. The idea that "good" code avoids anything non-obvious, that those are "exceptions", is frankly bizarre to me. Unless the code you write is 99% boilerplate or something.

Re: We should revisit literate programming in the agent era

#257

Post by palata »

crazygringo wrote: post #256
palata wrote: post #254

Earlier quoted context omitted.

> I'm assuming "lots of comments" means lots of meaningful comments. That's not what literate programming is. Literate programming says that you explain everything in a natural language. IMO, good code is largely unsurprising. I don't need comments for unsurprising code. I need comments for surprising code, but that is the exception, not the rule. Literate programming says that it is the rule, and I disagree.

> Literate programming says that you explain everything in a natural language. At a high level. Not line-by-line comments. > IMO, good code is largely unsurprising. I don't need comments for unsurprising code. I've never heard anything like that, and could not disagree more. Twenty different considerations might go into a single line of code. Often, one of them is something non-obvious. So you comment that thing. The…

> So you comment that thing. The idea that "good" code avoids anything non-obvious, that those are "exceptions", is frankly bizarre to me.

What I find interesting from the comments here is that there are obviously different perspectives on that. Granted, I cannot say that my way is better. Just as you cannot say that your way is better.

But I am annoyed when I have to deal with code following your standards, and I assume you are annoyed when you have to deal with code following mine :-).

Or maybe, I imagine that people who defend literate programming mean more comments than I think is reasonable, and people who disagree with me (like you) imagine that I mean fewer comments than you think is reasonable. And maybe in reality, given actual code samples, we would totally agree :-).

Communication is hard.

Re: We should revisit literate programming in the agent era

#258

Post by hkonte »

ajkjk wrote: post #60

I've had the same thought, maybe more grandiosely. The idea is that LLM prompts are code -- after all they are text that gets 'compiled' (by the LLM) into a lower-level language (the actual code). The compile process is more involved because it might involve some back-and-forth, but on the other hand it is much higher level. The goal is to have a web of prompts become the source of truth for the software: sort of lik…

[dead]

Re: We should revisit literate programming in the agent era

#259

Post by Izkata »

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…

> Literate programming sounds like "you need to comment pretty much everything because code is generally hard to understand".

You and I read code. Came so naturally for me that I didn't realize others don't. But over the years and with some weird chats I've realized that for a lot of developers it's more like "deciphering code", like they're slowly translating a human language they only vaguely know - and it never even crossed their mind that it was possible to learn a programming language to the point you could just read it.

Re: We should revisit literate programming in the agent era

#260

Post by robertwer »

There seems to be some evidence that literate programming style comments help humans to comprehend code they don't know. I found a paper investigating this.

Some folks from Google tested 1) how good LLMs can update existing code with LP style comments and 2) if that helps humans to better understand that enhanced code. (see the 2024 arXiv paper "Natural Language Outlines for Code").

If I remember correctly they had systematically tested how good humans could understand the enhanced code compared to no comments at all and they also tested different flavours of comments (line level, block level etc.).

The conclusion was: if you use the right amount of comments in the right style (intent explaining the purpose of the code on block level, not every line), it's very beneficial.

Post reply on HN