So this is my plea, from pure accessibility standpoint
I think we should be pretty cautious about assuming that a particular preference is an accessibility need. You have ADHD, and don't like long commit messages. I am not sure that is a universal ADHD trait.
Beyond that, accessibility doesn't mean "doing whatever is most agreeable to people with ADHD", it's about making reasonable accommodations that don't unduly burden people in general (my accessibility needs may be different from yours, which is why a lot of accessibility technology is behind preferences, so that individuals can choose high contrast, or reduced motion, or dark mode, or...).
My AuDHD is something that requires specific conditions for me to be able to work and function properly. Is that a preference? Not necessarily. Some things I just need in certain ways, and long blocks of texts can completely block working for me. And i mean things like two A4s of details for small changes. I can grind through it, but that leads its way to burnout, which I have few times every year (likely have never recovered.)
I dont know how to word it properly, something like "because these are my accessibility needs and I know many who share them."
Suppose it can still be turned into a preference over a need, but this is more a plea to keep people like me in mind when pasting that LLM generated wall of text in your commit message.
How it presents is different at different ages, but the "pattern of inattentive" or "hyperactivity-impulsivity" behaviors don't mean you can't comprehend a commit message worth of text. I push back as someone with ADHD because it doesn't speak for me.
Great if you don't struggle when faced with a "massive blast of information" as the author puts it but don't let that invalidate others' issues with inattention. Besides, how much "a commit message worth of text" is is precisely what is under question here.
Hyperfocus is absolutely an ADHD trait as well. Aside from that, do you know what else people with ADHD might struggle with? Reading every line of a MR thoroughly with zero signposting.
Yeah but the inattention/hyperfocus dial is actually in a very awkward location.
Can confirm, and I have never hyperfocused on a merge request, only for problems I've been solving. Maybe someone else gets hyperfocused on MRs, but I've never heard of that myself.
assuming that a particular preference is an accessibility need
In my experience, a lot of unnecessary hardship for neurodiverse and disabled people is caused by people assuming an accessibility needs is a preference. I think that is a bad path to go down, especially when everyone benefits from more accessibility, even those who don't need it to stand on equal footing.
That's the problem. This request is not something that benefits everyone.
Of course, it is possible to write a commit message that's too long for everyone:
"Alter the code to do multiplication instead of addition. As we all learned in elementary school, addition takes two numbers and..."
Basically every person is worse off reading this. If that is the complaint, then there's no real substance here. Everyone hates that. Perhaps the author's ADHD makes them more pained by the verbosity, but it's a universal complaint.
But if the issue is that there are certain comments that are beneficial to neurotypicals and present a difficulty for ADHD people, then we can't just say "we have to do this for accessibility." We have to consider the impact.
Basically every person is worse off reading this. If that is the complaint, then there's no real substance here. Everyone hates that. ... it's a universal complaint.
This is the most HackerNews piece of comment, and we're on lobste.rs!
You hate, I hate it, the author of this article hates it. But does everyone hate it? That's a big claim.
It might be that you don't personally interact with people that hate this, but I do. Every day. The reason this blog is relevant now, while you may have been right to claim it was redundant 5 years ago, is presumably because of LLM usage.
LLMs can tend to get very verbose, and write incredibly lengthy, redundant, fluff. The same people who don't bother correcting for their LLMs producing this fluff also seem to hugely overlap with the kinds of people who also don't read that fluff when they're on the receiving end, they instead get their LLMs to compress the noise into something more palatable, or outright offload the entire process of review to the LLM.
That being said, those kinds of people may also be unlikely to read this post, which may be a justification for calling it redundant.
But in any case, the point is that there are plenty of people out there who are either entirely indifferent on this topic because they offload dealing with it to their LLM, or who think that the giant blob of text they didn't bother to read is helpful. I know, because, as mentioned already, I regularly deal with these people.
Instead of saying "everyone hates this" Being precise, what I'd say is: everyone with sense hates it, but people do it because they are not thinking carefully, or they aren't exercising direction over their LLMs.
It would be reasonable to complain about that. But my point is that ADHD is a sideshow. Maybe it's worse for some people with ADHD, but it's bad for everyone.
My point was not "this isn't a problem." My point was "there's not an interesting claim about accessibility here", just some people being careful, and some people not being careful.
I've always (before AI, unrelated to AI) preferred overly verbose comments. Its shocking to some people I've worked with. A lot have come around to really liking it, a lot despise it. But it's my style.
My reasoning is pretty simple: it enforces a double-entry rule. If the comment doesn't agree with the code, either the comment is wrong, or the code is wrong (or both, but less likely). I've caught so much in my career by simply asking "these don't agree, which is right?" And, again, in the age of AI, this works that way too.
But at the end of the day, I think people should just comment however they want for their own projects. Its for you (the code author) after all.
As someone who has also been (in friendly manner) accused of sometimes writing more comments than code, I really like these kinds of comments. They help me retain the context of some local decisions I made when I later read back over the code, and it helps others build context when reviewing it or seeing it for the first time. I would argue that these kinds of comments are verbose, but not "extraneous detail" in the sense of the article. Obviously this is a highly subjective judgment, but I'd say that the example you shared is a good example of the "why, not what" adage.
// The first major issue is that on macOS, a lot of users
// put shell configurations in ~/.bash_profile instead of
// ~/.bashrc (or equivalent for another shell). This file is only
// loaded for a login shell so macOS users expect all their terminals
// to be login shells. No other platform behaves this way and its
// totally braindead but somehow the entire dev community on
// macOS has cargo culted their way to this reality so we have to
// do it...
actually provide useful context on why certain decisions were made a certain way. Looping back to LLMs though, I have yet to personally see LLM-generated code have comments of that quality. Usually they just end up being:
// 1. We do foo()
foo()
// 2. Next we need to bar()
bar()
// 3. Finally, baz
baz()
I don't have problem with the type of comments you linked. It's the mess where people add huge tables and bullet point lists for even very tiny changes.
I really appreciate that level of detail, but personally I much prefer it in a commit message for the commit that added the method rather than in a comment. I feel like commit messages are always in sync with the code whereas comments can drift.
At work, I tried to politely request (as part of a PR template): "please write your own description that explains the motivation for this change and any important design decisions that should be scrutinised / focused on in the review".
9/10 times, the LLM du jour chucks out the entire template and writes a tome of explanation, including counts of how many tests it added, checkboxes for each passing one, long tangents on trivial things. Reviewing has become a lot of fun.
Yeah, I'm having the same issue at work. I don't know who thought putting LLM generated commit message tooling everywhere was a good idea but you end up with the https://noslopgrenade.com/ problem in commits.
The commit messages/pull request descriptions don't have useful context on the motivation behind the change, the design decisions or rationale but instead devolve into a paragraph of explainin the minutia of the code. Stuff you can tell from reading the code anyway...
The only time I comment on what I'm doing instead of just why I'm doing it is when I'm not sure that I'm doing it correctly. Regex being the recurring source of pain.
Me as well! And there are times when you need solid description of everything. But what I see now is even small changes, like changing variable name, causes huge descriptions.
That's because an LLM wrote that description, and its operator did not keep it in line by telling it to be concise, precise, clear and avoid heavily redundant information.
Unfortunately there is no magic recipe that makes someone a good technical writer, especially with rules as coarse-grained as length of comments. And there is certainly no amount of prompt engineering that gets it done, either. It’s just a separate skill that needs to be cultivated. Probably the most accessible way to practice is by keeping a blog.
Interesting take. I'd say side by side (in terms of being as easy or even easier) with keeping a blog goes engaging in technical forums like lobste.rs, stack overflow, reddit etc. The feedback from fellow programmers is much faster, specially if you're trying to respond to questions or asking them. In a blog, God knows when somebody will ready your stuff, let alone tell you something was unclear.
LLMs write way too much though. It's so bad that I have configured claude to never write comments, because I was manually removing 98% of them (and rewriting the remaining 2%)
I generally like to write very descriptive commit messages, but shaping them like a news article where the most important information comes first with less important (but still relevant) details following. So like:
Headline: most important, make this as information dense as possible
First paragraph where I describe the change in less dense prose.
Following paragraphs for extra details. You probably don't need to read this as closely unless you're really struggling to understand the nature of the code change.
I also think people discount how important commit messages are for people reading the code after the fact, far in the future. When I'm digging through a codebase and wondering why a block is shaped a certain way I'm never disappointed when git blame points me to a novel of a commit message explaining, in excruciating detail, why this hacky looking approach was the last of a long line of better sounding, but ultimately incomplete, approaches.
Edit: To actually bring it back to the author's post (I meant to before!) putting explicit markers in communications seems like a good accommodation and useful in general. A simple "if you're reviewing this code you can stop reading now" in the middle of a commit message.
Extraneous detail I can ask about if I need to know.
Bold of you to assume that the person is still around to ask them. I started putting effort into writing commit messages when I started contributing to a +10 year old FLOSS code base. The only way to find out more information about why the code was there was to do some git archeology. Learned how to use Emacs' vc-annonate to do so with ease☨. Even in $work contexts, several times the author's of the code base I'm maintaining are long gone.
Commit messages are not only read during review. In fact most review UIs hide the commit messages. I'm guessing KDE uses fabricator which includes the commit message as part of the review process? In other scenarios most tools only show the commit message's title (and if not they can be configured to do so)
Based on your plea the issue but about poorly written commit messages. The following guidelines seem good.
keep commit messages, merge request descriptions and code comments clear, to the point, need-to-know basis. Do not explain what, but why.
Maybe the issue is that people that previously wrote 'Fix Bugz 🚀️' in the commit message now are using LLMs to write the commit messages to follow 'best practices'?
☨: My theory is that most people don't bother writing commit messages because they don't read them. And they don't read them because the activation energy to find them is high as they rely on GitHub's web interface (or equivalent WebUI) to browse commits.
This has to be balanced against a long-term need for posterity and successful got archaeology. You can't always ask for that extraneous detail later, either due to personnel changes or the context slipping out of one's brain. The best time to record that context is when you have it.
Maybe what you really want is the important detail first, clearly demarcated like a synopsis.
PR/code descriptions are not meant for what but the why. Tell me why the code looks like this and the reasons behind it. This is not only good for review but also for git history to find out why the code look like it does.
Keeping code descriptions simple is important. We can't read what we can't understand or focus on. But also, there is a lot of context that gets lost when developing software. Currently, that context lives in the heads of the author and anyone who has talked with them or studied the code.
But I think that context should be interwoven with the code more, not less. You won't always have the author to talk with. You want that written down somewhere you can always access it, in a place that is updated with the code. The best place for that in most development workflows at the moment is in git commit messages.
By all means, write a summary up top, but I also encourage people to provide further explanations for their code changes. Get that context out, even the stuff you don't think is important right now. Your future self will thank you.
Moving forward, I think we need to have a better approach than embedding that context commit messages (or at least having more places for different kinds of context). That's why I personally like Literate Programming, which I think provides more space to explain the "what" and "why" of the code.
hyperpape | 9 hours ago
I think we should be pretty cautious about assuming that a particular preference is an accessibility need. You have ADHD, and don't like long commit messages. I am not sure that is a universal ADHD trait.
Beyond that, accessibility doesn't mean "doing whatever is most agreeable to people with ADHD", it's about making reasonable accommodations that don't unduly burden people in general (my accessibility needs may be different from yours, which is why a lot of accessibility technology is behind preferences, so that individuals can choose high contrast, or reduced motion, or dark mode, or...).
[OP] Aks | 8 hours ago
Yeah i could be more clear in there, but..
My AuDHD is something that requires specific conditions for me to be able to work and function properly. Is that a preference? Not necessarily. Some things I just need in certain ways, and long blocks of texts can completely block working for me. And i mean things like two A4s of details for small changes. I can grind through it, but that leads its way to burnout, which I have few times every year (likely have never recovered.)
I dont know how to word it properly, something like "because these are my accessibility needs and I know many who share them."
Suppose it can still be turned into a preference over a need, but this is more a plea to keep people like me in mind when pasting that LLM generated wall of text in your commit message.
tentacloids | 7 hours ago
Everyone is different but I think it's pretty much one of the defining ADHD traits.
Accessibility-wise, everyone benefits from the accommodation of "get to the point already", so why push back?
Halkcyon | 7 hours ago
How it presents is different at different ages, but the "pattern of inattentive" or "hyperactivity-impulsivity" behaviors don't mean you can't comprehend a commit message worth of text. I push back as someone with ADHD because it doesn't speak for me.
tentacloids | 6 hours ago
Great if you don't struggle when faced with a "massive blast of information" as the author puts it but don't let that invalidate others' issues with inattention. Besides, how much "a commit message worth of text" is is precisely what is under question here.
hyperpape | 5 hours ago
Hyperfocus is absolutely an ADHD trait as well. Aside from that, do you know what else people with ADHD might struggle with? Reading every line of a MR thoroughly with zero signposting.
As for "this benefits everyone" see below: https://lobste.rs/c/xiqgjz.
tentacloids | 5 hours ago
Yeah but the inattention/hyperfocus dial is actually in a very awkward location.
The request isn't "please don't write anything"! What do you mean?
A summary absolutely benefits everyone.
[OP] Aks | 3 hours ago
Can confirm, and I have never hyperfocused on a merge request, only for problems I've been solving. Maybe someone else gets hyperfocused on MRs, but I've never heard of that myself.
JadedBlueEyes | 6 hours ago
In my experience, a lot of unnecessary hardship for neurodiverse and disabled people is caused by people assuming an accessibility needs is a preference. I think that is a bad path to go down, especially when everyone benefits from more accessibility, even those who don't need it to stand on equal footing.
hyperpape | 5 hours ago
That's the problem. This request is not something that benefits everyone.
Of course, it is possible to write a commit message that's too long for everyone:
Basically every person is worse off reading this. If that is the complaint, then there's no real substance here. Everyone hates that. Perhaps the author's ADHD makes them more pained by the verbosity, but it's a universal complaint.
But if the issue is that there are certain comments that are beneficial to neurotypicals and present a difficulty for ADHD people, then we can't just say "we have to do this for accessibility." We have to consider the impact.
atk | 5 hours ago
This is the most HackerNews piece of comment, and we're on lobste.rs!
You hate, I hate it, the author of this article hates it. But does everyone hate it? That's a big claim.
It might be that you don't personally interact with people that hate this, but I do. Every day. The reason this blog is relevant now, while you may have been right to claim it was redundant 5 years ago, is presumably because of LLM usage.
LLMs can tend to get very verbose, and write incredibly lengthy, redundant, fluff. The same people who don't bother correcting for their LLMs producing this fluff also seem to hugely overlap with the kinds of people who also don't read that fluff when they're on the receiving end, they instead get their LLMs to compress the noise into something more palatable, or outright offload the entire process of review to the LLM.
That being said, those kinds of people may also be unlikely to read this post, which may be a justification for calling it redundant.
But in any case, the point is that there are plenty of people out there who are either entirely indifferent on this topic because they offload dealing with it to their LLM, or who think that the giant blob of text they didn't bother to read is helpful. I know, because, as mentioned already, I regularly deal with these people.
hyperpape | 4 hours ago
Instead of saying "everyone hates this" Being precise, what I'd say is: everyone with sense hates it, but people do it because they are not thinking carefully, or they aren't exercising direction over their LLMs.
It would be reasonable to complain about that. But my point is that ADHD is a sideshow. Maybe it's worse for some people with ADHD, but it's bad for everyone.
My point was not "this isn't a problem." My point was "there's not an interesting claim about accessibility here", just some people being careful, and some people not being careful.
mitchellh | 8 hours ago
I've always (before AI, unrelated to AI) preferred overly verbose comments. Its shocking to some people I've worked with. A lot have come around to really liking it, a lot despise it. But it's my style.
For example, see this method:https://github.com/ghostty-org/ghostty/blob/4789bbdb9ef9e2a878b92d85ee89faeba1f48a87/src/termio/Exec.zig#L1408 but thats my general style everywhere in all languages across the last 15 years of my career. In the age of AI, I enshrine this in my AGENTS.md too. To be clear, the linked file and comments were human written, no AI at all.
My reasoning is pretty simple: it enforces a double-entry rule. If the comment doesn't agree with the code, either the comment is wrong, or the code is wrong (or both, but less likely). I've caught so much in my career by simply asking "these don't agree, which is right?" And, again, in the age of AI, this works that way too.
But at the end of the day, I think people should just comment however they want for their own projects. Its for you (the code author) after all.
hgrsd | 7 hours ago
As someone who has also been (in friendly manner) accused of sometimes writing more comments than code, I really like these kinds of comments. They help me retain the context of some local decisions I made when I later read back over the code, and it helps others build context when reviewing it or seeing it for the first time. I would argue that these kinds of comments are verbose, but not "extraneous detail" in the sense of the article. Obviously this is a highly subjective judgment, but I'd say that the example you shared is a good example of the "why, not what" adage.
ammar2 | 7 hours ago
Those comments are great! Things like:
actually provide useful context on why certain decisions were made a certain way. Looping back to LLMs though, I have yet to personally see LLM-generated code have comments of that quality. Usually they just end up being:
with stuff that is self-evident from the code.
[OP] Aks | 5 hours ago
I don't have problem with the type of comments you linked. It's the mess where people add huge tables and bullet point lists for even very tiny changes.
chrisl | 5 hours ago
I really appreciate that level of detail, but personally I much prefer it in a commit message for the commit that added the method rather than in a comment. I feel like commit messages are always in sync with the code whereas comments can drift.
quasi_qua_quasi | 4 hours ago
That comment starting on line 1467 is a masterpiece. I can feel the exhaustion.
hgrsd | 8 hours ago
At work, I tried to politely request (as part of a PR template): "please write your own description that explains the motivation for this change and any important design decisions that should be scrutinised / focused on in the review".
9/10 times, the LLM du jour chucks out the entire template and writes a tome of explanation, including counts of how many tests it added, checkboxes for each passing one, long tangents on trivial things. Reviewing has become a lot of fun.
ammar2 | 8 hours ago
Yeah, I'm having the same issue at work. I don't know who thought putting LLM generated commit message tooling everywhere was a good idea but you end up with the https://noslopgrenade.com/ problem in commits.
The commit messages/pull request descriptions don't have useful context on the motivation behind the change, the design decisions or rationale but instead devolve into a paragraph of explainin the minutia of the code. Stuff you can tell from reading the code anyway...
hyperpape | 5 hours ago
I've noticed the same behavior.
I'm considering saying adding "when composing commit messages, refer to commit-messages.md" to the agents.md file, and
Then commit-messages.md should have guidelines:
JulianSildenLanglo | 11 hours ago
The only time I comment on what I'm doing instead of just why I'm doing it is when I'm not sure that I'm doing it correctly. Regex being the recurring source of pain.
[OP] Aks | 10 hours ago
Me as well! And there are times when you need solid description of everything. But what I see now is even small changes, like changing variable name, causes huge descriptions.
atk | 8 hours ago
That's because an LLM wrote that description, and its operator did not keep it in line by telling it to be concise, precise, clear and avoid heavily redundant information.
schuelermine | 12 hours ago
Interesting, I’ve heard a lot of talk in the opposite direction (commit messages being too short)
rebeca | 6 hours ago
This post discussion goes side by side with the Chesterton middle finger one, which complains about the opposite (too short descriptions).
ahelwer | 5 hours ago
Unfortunately there is no magic recipe that makes someone a good technical writer, especially with rules as coarse-grained as length of comments. And there is certainly no amount of prompt engineering that gets it done, either. It’s just a separate skill that needs to be cultivated. Probably the most accessible way to practice is by keeping a blog.
rebeca | 4 hours ago
Interesting take. I'd say side by side (in terms of being as easy or even easier) with keeping a blog goes engaging in technical forums like lobste.rs, stack overflow, reddit etc. The feedback from fellow programmers is much faster, specially if you're trying to respond to questions or asking them. In a blog, God knows when somebody will ready your stuff, let alone tell you something was unclear.
[OP] Aks | 12 hours ago
They can be too short too, but having a novel in there makes no sense either.
wheybags | 8 hours ago
LLMs write way too much though. It's so bad that I have configured claude to never write comments, because I was manually removing 98% of them (and rewriting the remaining 2%)
gerow | 5 hours ago
I generally like to write very descriptive commit messages, but shaping them like a news article where the most important information comes first with less important (but still relevant) details following. So like:
I also think people discount how important commit messages are for people reading the code after the fact, far in the future. When I'm digging through a codebase and wondering why a block is shaped a certain way I'm never disappointed when git blame points me to a novel of a commit message explaining, in excruciating detail, why this hacky looking approach was the last of a long line of better sounding, but ultimately incomplete, approaches.
Edit: To actually bring it back to the author's post (I meant to before!) putting explicit markers in communications seems like a good accommodation and useful in general. A simple "if you're reviewing this code you can stop reading now" in the middle of a commit message.
PuercoPop | 5 hours ago
Bold of you to assume that the person is still around to ask them. I started putting effort into writing commit messages when I started contributing to a +10 year old FLOSS code base. The only way to find out more information about why the code was there was to do some git archeology. Learned how to use Emacs' vc-annonate to do so with ease☨. Even in $work contexts, several times the author's of the code base I'm maintaining are long gone.
Commit messages are not only read during review. In fact most review UIs hide the commit messages. I'm guessing KDE uses fabricator which includes the commit message as part of the review process? In other scenarios most tools only show the commit message's title (and if not they can be configured to do so)
Based on your plea the issue but about poorly written commit messages. The following guidelines seem good.
Maybe the issue is that people that previously wrote 'Fix Bugz 🚀️' in the commit message now are using LLMs to write the commit messages to follow 'best practices'?
☨: My theory is that most people don't bother writing commit messages because they don't read them. And they don't read them because the activation energy to find them is high as they rely on GitHub's web interface (or equivalent WebUI) to browse commits.
[OP] Aks | 3 hours ago
This is during review. If the information is important, it can be commented or added to the commit message.
We have been using Gitlab for years now
bjeanes | an hour ago
This has to be balanced against a long-term need for posterity and successful got archaeology. You can't always ask for that extraneous detail later, either due to personnel changes or the context slipping out of one's brain. The best time to record that context is when you have it.
Maybe what you really want is the important detail first, clearly demarcated like a synopsis.
nemith | 7 hours ago
PR/code descriptions are not meant for what but the why. Tell me why the code looks like this and the reasons behind it. This is not only good for review but also for git history to find out why the code look like it does.
liberty | 3 hours ago
Keeping code descriptions simple is important. We can't read what we can't understand or focus on. But also, there is a lot of context that gets lost when developing software. Currently, that context lives in the heads of the author and anyone who has talked with them or studied the code.
But I think that context should be interwoven with the code more, not less. You won't always have the author to talk with. You want that written down somewhere you can always access it, in a place that is updated with the code. The best place for that in most development workflows at the moment is in git commit messages.
By all means, write a summary up top, but I also encourage people to provide further explanations for their code changes. Get that context out, even the stuff you don't think is important right now. Your future self will thank you.
Moving forward, I think we need to have a better approach than embedding that context commit messages (or at least having more places for different kinds of context). That's why I personally like Literate Programming, which I think provides more space to explain the "what" and "why" of the code.
rebeca | 6 hours ago