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

261–270 of 270 posts

Re: We should revisit literate programming in the agent era

#261

Post by awesome_dude »

palata wrote: post #253
awesome_dude wrote: post #237

Earlier quoted context omitted.

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

> Do you write a comment before every for loop to explain how a for loop works?

Thank you for missing the point.

It's not about the WHAT, it's about the WHY.

For loops are obvious. O(n) being intentional instead of 'lazy' isn't obvious without context. That's what comments preserve - the decision rationale, not the syntax explanation.

A professional developer can read code. But they can't read the mind of the author who made a non obvious tradeoff. That's what comments preserve.

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

If you are going to make personal attacks, you should know that I work with actual professionals, and they understand that future maintainers, myself included, cannot read their mind on why they chose the path they did.

Re: We should revisit literate programming in the agent era

#262

Post by palata »

awesome_dude wrote: post #261
palata wrote: post #253

Earlier quoted context omitted.

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

> Do you write a comment before every for loop to explain how a for loop works? Thank you for missing the point. It's not about the WHAT, it's about the WHY. For loops are obvious. O(n) being intentional instead of 'lazy' isn't obvious without context. That's what comments preserve - the decision rationale, not the syntax explanation. A professional developer can read code. But they can't read the mind of the author…

> It's not about the WHAT, it's about the WHY.

And my point is that I don't care what it is about, I care about whether or not it is useful. I disagree with the literate programming idea that it's always useful to explain why you wrote the code the way you did, and your one example (justifying the O(n)) actually proves to me that I really don't care about your explanation in this particular case. So obviously your one example that I don't find useful won't convince me that all WHY comments are useful.

> O(n) being intentional instead of 'lazy' isn't obvious without context.

What does such a comment tell me?

- That you chose the O(n): it's the "please don't judge me, I know what I am doing" part. It's superfluous, because by default I assume that you know what you are doing.

- That you tried to do better and failed. If I believe that we don't need better than O(n), I don't care. If I believe that we need better than O(n), I will reason about doing it myself (no matter what you wrote).

- ... I can't see anything else.

Now sometimes, of course, there is real knowledge that needs to go into a comment. Like "This is a workaround due to a bug in version 1.4.2 of this proprietary dependency". But that's an exception. I can also totally imagine that some files implement something really tricky and deserve a lot of comments. But in my experience reading and contributing to a lot of open source code from many different projects, most code is not like that. The concept of "literate programming" doesn't say "be pragmatic about comments, use them when it matters", it says "comment the code because it always helps".

> If you are going to make personal attacks

I am not making personal attacks, I genuinely believe that you are perfectly able to read and understand code that does not follow the "literate programming" paradigm. And if you are not, I still don't see that as a personal attack: with experience you will definitely get there.

> cannot read their mind on why they chose the path they did.

I just want to repeat it here: it does not matter at the implementation detail level. You may want to document the architecture (including technology choices) of course, but that's not what literate programming is about. You probably want to document the public API (because using an API generally does not require reading the code, and the implementation may be proprietary), but again that's not what literate programming is about. But the implementation details? Unless it's surprising (e.g. a necessary workaround), I don't care about why it was written the way it was, I just care about understanding what it does such that I can reason about it.

Re: We should revisit literate programming in the agent era

#263

Post by eru »

1718627440 wrote: post #247
necovek wrote: post #240

Earlier quoted context omitted.

Certainly, but merges are treated differently by default, and getting to this sort of output would require "custom" tooling for things like "git log". Whereas bzr just did the expected thing.

You can select whether you want the diff to the first or the second parent, which is the difference between collapsing and expanding merges. You can also completely collapse merges by showing first-parent-history. Or I do not understand what you mean with "the expected thing".

Yes, `git log --first-parent` has been a godsend for coping with our team's messy non-cleaned up history.

Re: We should revisit literate programming in the agent era

#264

Post by eru »

1718627440 wrote: post #241
eru wrote: post #165

Earlier quoted context omitted.

Sure, but you are still supposed to clean things up to make the life of the reviewer easier. There's an inherent tension between honest history and a polished 'lie' to make the reviewer's life easier.

The WIP commits I initially recorded also don't necessarily existed as such in my file system and often don't really work completely, so I don't know why the commit after a rebase is any more a lie then the commit before the rebase.

It's a 'lie' in the sense that you are optimising for telling a convenient and easy to understand story for the reviewer where each commit works atomically.

Re: We should revisit literate programming in the agent era

#265

Post by awesome_dude »

palata wrote: post #262
awesome_dude wrote: post #261

Earlier quoted context omitted.

> Do you write a comment before every for loop to explain how a for loop works? Thank you for missing the point. It's not about the WHAT, it's about the WHY. For loops are obvious. O(n) being intentional instead of 'lazy' isn't obvious without context. That's what comments preserve - the decision rationale, not the syntax explanation. A professional developer can read code. But they can't read the mind of the author…

> It's not about the WHAT, it's about the WHY. And my point is that I don't care what it is about, I care about whether or not it is useful . I disagree with the literate programming idea that it's always useful to explain why you wrote the code the way you did, and your one example (justifying the O(n)) actually proves to me that I really don't care about your explanation in this particular case. So obviously your o…

You make a lot of comments for someone that thinks it should be obvious and there's no need for comments.

Re: We should revisit literate programming in the agent era

#266

Post by palata »

awesome_dude wrote: post #265
palata wrote: post #262

Earlier quoted context omitted.

> It's not about the WHAT, it's about the WHY. And my point is that I don't care what it is about, I care about whether or not it is useful . I disagree with the literate programming idea that it's always useful to explain why you wrote the code the way you did, and your one example (justifying the O(n)) actually proves to me that I really don't care about your explanation in this particular case. So obviously your o…

You make a lot of comments for someone that thinks it should be obvious and there's no need for comments.

Again you prove my point: natural languages are ambiguous and communication is hard.

And maybe also that you don't seem to make the difference between natural languages and programming languages: I have not been commenting code here. If you can't make the difference, maybe it explains why you want to mix them.

Re: We should revisit literate programming in the agent era

#267

Post by just6979 »

CharlieDigital wrote: post #217
zozbot234 wrote: post #216

Earlier quoted context omitted.

In my experience, LLM-added comments are too silly and verbose. It's going to pollute its own context with nonsense and its already limited ability to make sense of things will collapse. LLMs have plenty of random knowledge which is occasionally helpful, but they're nowhere near the standard of proper literacy of even an ordinary skilled coder, let alone Dr. Knuth who defined literate programming in the first place.

The output of an LLM is a reflection of the input and instructions. If you have silly and verbose comments, then consider improving your prompt.

"then consider improving all your training data and reinforcement feedback"

Fixed that for you.

The input is sooo much more than your prompt, that's kind of the point.

Re: We should revisit literate programming in the agent era

#268

Post by awesome_dude »

palata wrote: post #266
awesome_dude wrote: post #265

Earlier quoted context omitted.

You make a lot of comments for someone that thinks it should be obvious and there's no need for comments.

Again you prove my point: natural languages are ambiguous and communication is hard. And maybe also that you don't seem to make the difference between natural languages and programming languages: I have not been commenting code here. If you can't make the difference, maybe it explains why you want to mix them.

And silence doesn't achieve the goal at all, as you continually prove.

Re: We should revisit literate programming in the agent era

#269

Post by kalaksi »

1718627440 wrote: post #242
kalaksi wrote: post #135

Earlier quoted context omitted.

Sounds easier (for everybody) to just use comments.

You put past failed implementation in comments? That sounds like a nightmare. I rather only include a short description in the comment that can then link to the older implementation if necessary.

What? No, a short explanation of why some approach doesn't work well.

Re: We should revisit literate programming in the agent era

#270

Post by gogopromptless »

cfiggers wrote: post #64
spawarotti wrote: post #33

Earlier quoted context omitted.

There is at least one startup doing it already (I'm not affiliated with it in any way): https://promptless.ai/

Thanks for the pointer. That looks more to me like it's totally synthesizing the docs for me. I can see someone somewhere wanting that. I would want a UX more like a compiler warning. "Comment on line 447 may no longer be accurate." And then I go fix it my own dang self.

Ha, this is funny (also sad for me because I failed to explain on website clearly) because you have described exactly what it does as an example of what it can't do.

The core loop is more like a truffle-hunting pig than a ghostwriter. Promptless watches for signal that your product is behaving differently from the live documentation. It watches PRs opened/merging, Slack threads, support tickets. Then like a pig alerting on a truffle it shows up like "hey, this section over here doesn't match what the code/product does anymore."

Now of course we'll also generate a first draft of a suggested fix, but I want to say 40% of tech writers just like knowing when things changed.

Its a proper union find algorithm, where every suggestion links back to the source that triggered it, but multiple source do get linked up to just a single canonical suggestion. So you don't get duplicate alerts if people keep talking for weeks about a fix going out in the next release.

Obviously I've got some more work to do on the website again but c'est la vie.

Post reply on HN