The problem with literate programming is that most people aren’t good writers, and they aren’t interested in developing their writing skills - they only want to code.
Already it’s pulling teeth just to get literate commit messages…
back
5 comments
The other problem is that literate programming works well for code that has complicated ideas behind a small amount of code, but most businesses code is simple ideas behind a lot of boilerplatey code.
The hard part is in making it all fit together, not explaining what each part means.
it might be worth separating out the clever business-specific algorithms, etc. these can be done with literate programming and then the rest of the plumbing can be done as usual.
Side note, regarding commit messages: I have a few colleague who will go through the commit message just as thoroughly as they do the code, and match up the code with the commit. Over the past few years that has thought me to write pretty decent commit messages, to the point where I go "That is nicely done" when encountering my own commits.
Still can't write outside commit messages, but I guess that can be learned as well.
You know who is a good writer? LLMs. Imagine a model interrogating you about a piece of code and writing perfect documentation.
JK, the LLM will get bad input and it will spit out bad output.
LLM's tend to write classic "what, not why" comments/commit messages. The idea of the LLM interrogating the programmer for the "why" is interesting, though.
Or maybe reading the ticket? (That might just be moving the problem somewhere else though).
I wonder if an LLM could make ”atomic commits” out of my N pending changes.
It almost can... You can use something like gptcommit to automatically create a commit message. But the results are pretty bad. It can't produce anything beyond placeholder/filler text.
I don't need a message explaining we introduced a if to return when i is greater than len(items). I want a commit explaining why it blew up in production after being in production for over a year. What changed ? Did it had any other implications ? There is any ticket for this bug, or maybe a thread in slack ?
>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.
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.
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.
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.
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.
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.
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.
>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.
Surely you do it often enough that an extra 90s would not be an undue cost?
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.
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.
I do squash them where appropriate.
I do use git stash where appropriate.
These arent nonobvious novelties, save perhaps to junior engineers.
Well, that is kind of what you sound like.
> 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.
You make a new commit every 12 minutes for eight hours?
> 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.
These questions are not made in bad faith.
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.
Do you not have code reviews?
Seems like many devs don't even like to code. They just want to get paid.
(Not suggesting there's something wrong with that, per se. But good luck getting someone's who just in it for the money to go above and beyond.)