5 ms·

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

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…

lupire 2y ago
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.
- exe34 2y ago
  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.
mrweasel 2y ago
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.
hitchstory 2y ago
>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.
- paulddraper 2y ago
  Surely you do it often enough that an extra 90s would not be an undue cost?
  - hitchstory 2y ago
    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.
    - kragen 2y ago
      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.
      - hitchstory 2y ago
        I do squash them where appropriate. I do use git stash where appropriate. These arent nonobvious novelties, save perhaps to junior engineers.
        kragen 2y ago
        Well, that is kind of what you sound like.
        Supermancho 2y ago
        > 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.
kubb 2y ago
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.
- toxik 2y ago
  I wonder if an LLM could make ”atomic commits” out of my N pending changes.
  - nzach 2y ago
    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 ?
- flir 2y ago
  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).
sparker72678 2y ago
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.)

lupire 2y ago

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.

exe34 2y ago
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.

mrweasel 2y ago

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.

hitchstory 2y ago

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

paulddraper 2y ago
Surely you do it often enough that an extra 90s would not be an undue cost?
- hitchstory 2y ago
  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.
  - kragen 2y ago
    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.
    - hitchstory 2y ago
      I do squash them where appropriate. I do use git stash where appropriate. These arent nonobvious novelties, save perhaps to junior engineers.
      - kragen 2y ago
        Well, that is kind of what you sound like.
        Supermancho 2y ago
        > 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.

kubb 2y ago

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.

toxik 2y ago
I wonder if an LLM could make ”atomic commits” out of my N pending changes.
- nzach 2y ago
  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 ?
flir 2y ago
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).

sparker72678 2y ago

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