News for hackers. Stuff that matters.
Re:Literate programming: Knuth is doing it wrong (2014) by hitchstory on Monday January 13, 2025 @10:20AM (#42684351)
>Already it’s pulling teeth just to get literate commit messages…

I usually push back on this because those commit messages almost never actually get read. It's an investment whose dividends are nebulous and hard to pin down.

It's rare that I look at a commit, and it's even rarer that I read it and wish that it had a better message.

There are all sorts of other documentation I routinely wish people put more effort into writing (comments, a "why" attached to every test, how to guides, tutorials), but rarely ever a commit message.

Re:Literate programming: Knuth is doing it wrong (2014) by norir on Monday January 13, 2025 @10:53AM (#42684778)
Writing good commit messages can be good self-promotion. You may not realize who is watching the repo and this is an easy way to differentiate yourself from you colleagues and make your work appear interesting and important.

Also, I have found that writing commit messages often forced me to rework a poor solution whose weakness became apparent only when I tried to explain it. In other words, often the value of the commit message is not the message itself but rather the process that produced it. It's a bit like musical scales. Almost no one is performing scales at a concert but also almost no one is performing without scales as a part of their regular practice.

Re:Literate programming: Knuth is doing it wrong (2014) by hitchstory on Monday January 13, 2025 @11:29AM (#42685234)
>can be good self-promotion. You may not realize

When I said nebulous and hard to pin down this is kinda what I meant.

Do you routinely monitor commit messages on adjacent teams' repos? I dont. I dont know anybody who does. When I want to know something about their code I ping them a slack message and vice versa.

I dont think the CTO is reading commit messages either, theyre too busy.

I think it's good to ask when and why people actually do read commit messages to make sure what you write aligns with what they want to see.

Re:Literate programming: Knuth is doing it wrong (2014) by fsmv on Monday January 13, 2025 @11:39AM (#42685347)
If you wrote better commit messages you might look at them more because they're a lot more useful.

At work I see it as explaining why the code is there so when people check the blame layer they can find out and not delete my code if my reason is still relevant.

At home it helps a lot to write changelogs later when I do a release and it helps so much to see the last few commits when I pick a project up again after a month or two.

Re:Literate programming: Knuth is doing it wrong (2014) by hitchstory on Monday January 13, 2025 @11:47AM (#42685460)
I mostly just message the person who wrote it if I have questions when I look at a commit and have questions.

I suppose if I painstakingly write 1000 beautiful commit messages I could save myself from having that one conversation when somebody else has a question about one of those commits.

Re:Literate programming: Knuth is doing it wrong (2014) by moe_sc on Monday January 13, 2025 @12:01PM (#42685640)
That doesn't sound future proof.

People leave projects/companies, people forget.

Code comments are also far from good. They have the same issue as duplicatet code. Comment and code age indiviually. Now you have to maintain both and it's for them to diverge.

Git commits are a snapshot of the codebase. Commit messages in them are pinned to a code version. Comments in commit messages are therefore always tied to the right version of code.

Re:Literate programming: Knuth is doing it wrong (2014) by hitchstory on Monday January 13, 2025 @12:10PM (#42685766)
People leaving is a great reason to write literate tests and other kinds of docs - the kind people actually look for and want to read.

If somebody asks a question that can only be asked by looking in a commit message that usually represents a failure in one of those docs.

Re:Literate programming: Knuth is doing it wrong (2014) by kccqzy on Monday January 13, 2025 @03:24PM (#42688619)
I'm an introvert. I don't want anyone to message me (or worse, set up a meeting with me) just to understand what my commit does.

Furthermore writing is itself a way to enhance clarity of thinking. Very often during the process of writing out a commit message I realize something else in the commit is missing.

Re:Literate programming: Knuth is doing it wrong (2014) by paulddraper on Monday January 13, 2025 @10:49AM (#42684751)
Surely you do it often enough that an extra 90s would not be an undue cost?
Re:Literate programming: Knuth is doing it wrong (2014) by hitchstory on Monday January 13, 2025 @11:27AM (#42685196)
I'd estimate I probably commit ~30-50 times a day. I dig into and read a commit message once every 3 months.

A 90 seconds a commit that's an hour a day spent writing beautiful commits.

That one hour a day could be substituted with one conversation "hey, why did you do xyz in [ linktocommit ]?" every 3 months.

If you dont do these back of the envelope calculations in your head when trying to figure out if something is worth doing I highly encourage it.

Re:Literate programming: Knuth is doing it wrong (2014) by kragen on Monday January 13, 2025 @11:47AM (#42685457)
Maybe you should be using `git stash` and `git stash pop` rather than commits. Or go back and squash your 30–50 commits into one or two, which might take ten minutes. What you're doing is better than not using version control at all, but only barely.
Re:Literate programming: Knuth is doing it wrong (2014) by hitchstory on Monday January 13, 2025 @11:50AM (#42685492)
I do squash them where appropriate.

I do use git stash where appropriate.

These arent nonobvious novelties, save perhaps to junior engineers.

Re:Literate programming: Knuth is doing it wrong (2014) by kragen on Monday January 13, 2025 @02:10PM (#42687352)
Well, that is kind of what you sound like.
Re:Literate programming: Knuth is doing it wrong (2014) by Supermancho on Monday January 13, 2025 @02:56PM (#42688178)
> Well, that is kind of what you sound like.

This is what senior engineers do. Interrupted to switch tasks every 10 min. Make your good changes as a commit and move to the next task. Maybe you get back to it today, maybe not.

Re:Literate programming: Knuth is doing it wrong (2014) by kragen on Wednesday January 15, 2025 @10:28AM (#42711984)
That's definitely not how Jeff Dean and Sanjay Ghemawat wrote MapReduce and Bigtable. I'm sure what you're saying is correct at many companies (I've seen a few), but it's a stupid policy, depriving them of the benefit of having senior engineers.
Re:Literate programming: Knuth is doing it wrong (2014) by lanstin on Monday January 13, 2025 @12:36PM (#42686076)
Do you not have code reviews?
Re:Literate programming: Knuth is doing it wrong (2014) by paulddraper on Monday January 13, 2025 @02:21PM (#42687536)
You make a new commit every 12 minutes for eight hours?
Re:Literate programming: Knuth is doing it wrong (2014) by Supermancho on Monday January 13, 2025 @02:59PM (#42688218)
> You make a new commit every 12 minutes for eight hours?

You only work 8 hours? Your changes are that big? These are bad faith questions.

Re:Literate programming: Knuth is doing it wrong (2014) by paulddraper on Monday January 13, 2025 @05:29PM (#42690376)
These questions are not made in bad faith.
Re:Literate programming: Knuth is doing it wrong (2014) by hitchstory on Monday January 13, 2025 @06:56PM (#42691283)
That sounds like a reasonable average, yeah. Some tiny changes take 45 seconds, some harder changes take 40 minutes.

I find that working in working code increments that are as small as possible to be ideal.