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

241–250 of 270 posts

Re: We should revisit literate programming in the agent era

#241

Post by 1718627440 »

eru wrote: post #165
1718627440 wrote: post #125

Earlier quoted context omitted.

If you throw away commit messages, that is on you, it is not a limitation of Git. If I am cleaning up before merging, I'm maybe rephrasing things, but I am not throwing that information away. I regularly push branches under 'draft/...' or 'fail/...' to the central project repository.

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.

Re: We should revisit literate programming in the agent era

#242

Post by 1718627440 »

kalaksi wrote: post #135
1718627440 wrote: post #125

Earlier quoted context omitted.

If you throw away commit messages, that is on you, it is not a limitation of Git. If I am cleaning up before merging, I'm maybe rephrasing things, but I am not throwing that information away. I regularly push branches under 'draft/...' or 'fail/...' to the central project repository.

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.

Re: We should revisit literate programming in the agent era

#243

Post by 1718627440 »

crazygringo wrote: post #207
1718627440 wrote: post #106

Earlier quoted context omitted.

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…

Because comments are a bad fit to encode the evolution of code. We implemented systems to do that for a reason.

> The VCS history has to be actively pulled up and reading through it is a slog

Yes, but it also allows to query history e.g. by function, which to me gets me to understand much faster than wading through the current state and trying to piece information together from the status quo and comments.

> history becomes exceptionally difficult to retrace in certain kinds of refactoring.

True, but these refactorings also make it more difficult to understand other properties of code that still refers to the architecture pre-refactoring.

> I have never understood the idea of relying on code history instead of code comments. It seems like it's all downsides, zero upsides.

Comments are inherently linear to the code, that is sometimes what you need, for complex behaviour, you rather want to comment things along another dimension, and that is what a VCS provides.

What I write is this:

    /* This used to do X, but this causes Y and Z 
       and also conflicts with the FOO introduced 
       in 5d066d46a5541673d7059705ccaec8f086415102.
       Therefore it does now do BAR, 
       see c7124e6c1b247b5ec713c7fb8c53d1251f31a6af */

Re: We should revisit literate programming in the agent era

#244

Post by 1718627440 »

necovek wrote: post #132
eru wrote: post #119

Earlier quoted context omitted.

Git history is incredible important, yes, but also limited. Practically, it only encodes information that made it into `main`, not what an author just mulled over in their head or just had a brief prototype for, or ran an unrelated toy simulation over.

In fairness to GP, they said VCS, not Git, even if they are somewhat synonomous today. Other VCSes did support graph histories. Still, "3rd dimension" code reasoning (backwards in time) has never been merged well with code editing.

> In fairness to GP, they said VCS, not Git

I did say VCS, but I also don't know what Git is missing in this relation.

> Other VCSes did support graph histories.

How does Git do not?

> Still, "3rd dimension" code reasoning (backwards in time) has never been merged well with code editing.

Maybe it's not perfect, but Git seems to do that just fine for my taste. What is missing there?

Re: We should revisit literate programming in the agent era

#245

Post by 1718627440 »

eru wrote: post #162
necovek wrote: post #132

Earlier quoted context omitted.

In fairness to GP, they said VCS, not Git, even if they are somewhat synonomous today. Other VCSes did support graph histories. Still, "3rd dimension" code reasoning (backwards in time) has never been merged well with code editing.

> Other VCSes did support graph histories. Yes, git ain't the only one, but apart from interface difference, they are pretty much compatible in what they allow you to record in the history, I think? Part of the problem here is that we use git for two only weakly correlated purposes: - A history of the code - Make nice and reviewable proposals for code changes ('Pull Request') For the former, you want to be honest. Fo…

> - A history of the code

Which is a causal history, not a editing log. So I don't perceive these to be actually different.

Re: We should revisit literate programming in the agent era

#246

Post by palata »

dinfinity wrote: post #224
palata wrote: post #171

Earlier quoted context omitted.

My point is that if your code is well written, it is self-documenting. Obviously Class1 and var2 are not self-documenting.

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 people don't update them" and "I can see less of the code".

Well no, that's not my argument. I have been navigating code for 20 years and in good codebases, comments are rare and describe something "surprising". Good code is hardly surprising.

My problem with "literate programming" (which means "add a lot of comments in the implementation details") is that I find it hard to trust developers who genuinely cannot understand unsurprising code without comments. I am fine with a junior needing more time to learn, but after a few years if a developer cannot do it, it concerns me.

Re: We should revisit literate programming in the agent era

#247

Post by 1718627440 »

necovek wrote: post #240
eru wrote: post #231

Earlier quoted context omitted.

I am not quite sure what you are describing here. Git's underlying commit graph is a DAG. You can use different, custom merge-drivers (or whatever it's called) for Git to get the behaviour you describe here.

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

Re: We should revisit literate programming in the agent era

#248

Post by palata »

psychoslave wrote: post #225
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. Programming languages can be ambiguous too. The thing with formal languages is more that they put a stricter and narrower interpretation freedom as a convention where it's used. If anything there are a subset of human expression space. Sometime they are the best tool for the job. Sometime a metaphor is more apt. Sometime you nee…

Programming languages are non-ambiguous, in the sense that there is no doubt what will be executed. It's deterministic. If the program crashes, you can't say "no but this line was a joke, you should have ignored it". Your code was wrong, period.

Re: We should revisit literate programming in the agent era

#249

Post by cindyllm »

palata wrote: post #248
psychoslave wrote: post #225

Earlier quoted context omitted.

>Natural languages are ambiguous. That's the reason why we created programming languages. Programming languages can be ambiguous too. The thing with formal languages is more that they put a stricter and narrower interpretation freedom as a convention where it's used. If anything there are a subset of human expression space. Sometime they are the best tool for the job. Sometime a metaphor is more apt. Sometime you nee…

Programming languages are non-ambiguous, in the sense that there is no doubt what will be executed. It's deterministic. If the program crashes, you can't say "no but this line was a joke, you should have ignored it". Your code was wrong, period.

[dead]

Re: We should revisit literate programming in the agent era

#250

Post by palata »

zdragnar wrote: post #233
palata wrote: post #184

Earlier quoted context omitted.

I would call your example "bad code". Do you disagree with that?

Not at all. I'm just pointing out that code does not intrinsically convey intent, only implementation. To use a less trite example, I'd probably find some case where a word or name can have different meanings in different contexts, and how that can be confusing rather than clarifying without further documentation or knowledge of the problem space. Really though, any bug in the code you write is a deviation between in…

I feel like we're going from "literate programming" to "sometimes it makes sense to add comments". I agree with the latter. Good code is mostly unsurprising, and when it is surprising it deserves a comment. But that is more the exception than the rule.

Literate programming makes it the rule.

Post reply on HN