Please keep code descriptions simple
50 points by Aks
50 points by Aks
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...
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:
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.
Those comments are great! Things like:
// 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()
with stuff that is self-evident from the code.
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.
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.
That's an intriguing example. By my count (bearing in mind je ne parle pas Zig), feels like two thirds of that doc comment describe API contracts that the language cannot express? (Expectations on the comptime & allocator arguments; barring the "used by macOS" sentence) Wouldn't dock points for verbosity then, but I'd prefer more structured signposting, like some doc formatting convention to itemize constraints for each argument.
Not sure why; maybe because I suspect I'll use the doc more as a reference to come back to, than as a story to read cover-to-cover; so if the function has n arguments I'll probably come back to the doc n times, each time meaning to fish out information about one specific argument. If the doc has m paragraphs of unstructured prose, then that's n×m scans; vs just n if there's a clear sign telling me "wondering about this argument? lookee here".
(The first paragraph's "this isn't as straightforward as it seems" triggers my bonhomie allergy - what do you mean you thought this would be straightforward? Now I have to stay on guard because every time I don't see that caveat, I have to assume the author figured "well this is as straightforward as it seemed, turns out" and that makes me anxious.
That's a me thing, of course; ISTM we could s/This isn't as straightforward as it seems since we deal with/Deal with subtleties like/ with no loss of information, but I don't think it'd be objectively better; would just cater to my personal taste more)
Sorry for hyperfocusing on this specific example¹; tickled my brain and prompted me to reflect on what I (don't) like about "verbose" code comments. The OP understandably refrained from pointing fingers, so thanks for providing the case study, that helped kickstart my own reflection.
¹ Speaking of hyperfocusing: reading replies to this thread, I now realize you were pointing at the whole method, not just the /// doc comments 🤣
I'm torn then; OT1H I do love a good war story, OTOH I do try to express things like To figure out a lot of this logic I read the login.c source code in the OSS distribution Apple provides for macOS in a more authoritative & terse way, e.g. "xref login.c from macOS OSS distrib $VERSION". But then again nowadays it's also nice to know there's a human on the phone. But then again again the robots can romantasy with the best of us, so a good story no longer necessarily connotes a human connection. So unless it's a very good story I might still prefer the mechanical xref. "Torn then".
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.
Problem there is you don't see the commit messages 3 months later when you're trying to figure out why flangeTheBoat is being called with NEVER_UNDERSIDED_WEASEL.
(An editor which did show commit messages whilst editing might be interesting but then how do you decide which commit messages to show? The last one? Might not be relevant. All? Good luck with your 96" portrait monitor and 4pt font.)
git log -S NEVER_UNDERSIDED_WEASEL (the pickaxe operator) would help in that case. I also use git praise and git log --grep quite often. You're right though, editor support is very useful too. Emacs' vc-annotate is very handy.
Same - my biggest complaint about Codex is that this sort of comment seems something that the model avoid in general to their detriment. More recent versions are better at this, but 5-5.3 would actively remove them without guidance in your AGENTS.md. I've seen the reasons why, and think this only generally gets better by complaining that it should be better. Bonus points, docs colocated with code saves tokens spent on future inference (especially since that inference was already done to create the code in the first place).
My reasoning is similar, but more that code doesn't matter mostly anymore. If you have a spec, a doc comment, unit tests, integration tests, non deterministic validation, static analysis, etc. then the code is generally the least important thing in any program any more.
One thing I would suggest is that optimizing for reading is a good idea - look for 80 char+ lines of comments (I personally prefer 100) as these tend to be generally more readable for prose than shorter lines. Comments aren't poetry. Obv. YMMV this is subjective etc.
I agree with this style of comment. I like to spell out the subtleties and decisions that were made that resulted in the code as it exists. I feel this helps me, or maybe someone else, get back into the correct frame of mind when modifying the code later.
Not a fan of that example to be honest, too verbose for my taste. Here is the equivalent from alacritty:
https://github.com/alacritty/alacritty/blob/master/alacritty_terminal/src/tty/unix.rs#L183
Might not have all the same detail but it gives you the gist of it in a much more compact way and weaved in at the right places. This style of comment is more likely to be kept up to date when the code changes.
This comment section has really disappointed me. I’m AuDHD myself and struggle with overwhelm myself. Huge walls of text, a CLI with too many spinners and progress bars, etc. These all make our brains go "wtf, can't look at that, shutting down."
“Don’t dump an excessive amount of text in commit messages” is a reasonable request. I think we can reasonably disagree on what "excessive" means. I get that it's hard to even have this conversation without having actual examples to point at so we can find where we're not in alignment on "excessive".
(Aside: for a single data point, LLMs are really bad at signal to noise ratio in my experience. That doesn't mean you or your coworker are better. No one is asking for perfect, we're just asking for you to care.)
I prefer a paragraph-sized comment in code because it means I don't need to read the tea leaves trying to suss out whether something was intended or incidental. People with Autism already do that all day in social interactions, on Slack, etc and it's truly exhausting.
If you acknowledge that Autism, ADHD, etc exist and still call "please don't flashbang me with text" a personal preference, kind of fuck you. It's so irritating to go through life this way and have to explain and justify the need for accommodations.
I've seen "AuDHD" before, assuming it was a typo. What does this mean? Autism with comorbid ADHD (or vice versa)?
Yup! Lots of folks with Autism also happen to suffer from some form of ADHD, and having to deal with both at the same time leads to challenges that are unique to this comorbity, as opposed to "just" one of them.
Of course both ADHD and ASD are not one-dimensional conditions, so there is a lot of variance in symptoms and how well an individual can deal with everything, even before combining the two.
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.
This is excellent advice. I wish more people would learn to structure their communications in such a way. I feel people don't think about commit messages that much. Often a commit message is either too terse or else just a brain dump.
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.
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...).
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.
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.
So you've gone from a generalization about who hates it, to "people who disagree with me are stupid".
I dislike excessive commenting, with a passion, but some people clearly do prefer heavy commenting, and you're making a blanket statement that they are stupid for doing so. I don't think people are stupid for having a different idea of what the correct balance for commenting is.
I know plenty of people dislike my approach: I generally do not comment code. The code should be self explanatory, and if it is not, the code is likely bad. I only comment in the off case that the code is doing something for reasons that are non-obvious, or have non-local constraints. It irks me when people say "how do I know what it does", because the answer is: read the code. Comments trivially drift from actual code behavior - to me it is obvious that people tend to over-comment, and that that causes problems.
Should I now claim that this is the only opinion anyone with sense should have? After all I have a lot of experience, including with very complex code.
Or maybe you think I'm a different person who has no sense?
Maybe the level of commenting is an experience thing - over time, and with experience, people adjust how they write code, and how they comment. I'm guessing that early on in their careers being told they have no sense or are stupid, I'm guessing that certainly it will make them feel welcome on forums like this.
The point is that labeling people as having no sense because you disagree with them is a shitty thing to do.
"this" referred to my contrived example of a completely over the top comment.
I agree that there will be some cases where reasonable people can disagree. My underlying point remains valid--we cannot just say "some people have ADHD, we must comment in the style that helps them." We have to consider the impact on the overall experience of everyone involved.
This request is not something that benefits everyone.
That isn't really relevant, because it's not a prerequisite for a reasonable adjustment.
You seem to acknowledge that more consise messages can be more pleasant and useful. Even when you can't fit all the information in to a single paragraph, you can summarise the writing at the start.
So why the objection to using them where possible, when it's a reasonable request from someone you are hypothetically working with?
It's absolutely relevant for reasons I've already stated.
I can turn reduced motion on or off without affecting your phone. So it doesn't have to benefit everyone, just an appreciable group of people. We can just add it as an option.
But changing the git commit messages affects everyone who works in the system. We have to try to do what's best for readers overall, not just accomodate one particular reader.
I am not sure that is a universal ADHD trait.
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?
pretty much one of the defining ADHD traits.
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.
As for "this benefits everyone" see below: https://lobste.rs/c/xiqgjz.
Hyperfocus is absolutely an ADHD trait as well.
Yeah but the inattention/hyperfocus dial is actually in a very awkward location.
zero signposting
The request isn't "please don't write anything"! What do you mean?
this benefits everyone
A summary absolutely benefits everyone.
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.
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.
Extraneous detail I can ask about if I need to know.
This is during review. If the information is important, it can be commented or added to the commit message.
I'm guessing KDE uses fabricator
We have been using Gitlab for years now
Bold of you to assume that the person is still around to ask them.
Or remembers anything about it. I routinely read my commit messages when asked about changes I did.
Interesting, I’ve heard a lot of talk in the opposite direction (commit messages being too short)
This post discussion goes side by side with the Chesterton middle finger one, which complains about the opposite (too short descriptions).
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%)
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.
Google's guidelines for commit/CL descriptions are a good starting point and have proven to be quite effective at helping a wide distribution of engineers to understand changes to a large and rapidly evolving code base. They're worth a look:
https://google.github.io/eng-practices/review/developer/cl-descriptions.html
I didn’t have time to write you a short description… so I wrote you a long one instead.
Isn't the whole idea of commit messages that you first have your summary line and then the "big part of text" or if necessarily go into more detail as you progress through the text.
I think it makes sense to have these kinds of structures everywhere going from core important parts to gradually more detailed information, because on one hand you might not need the details, but on the other hand they might later in time end up being important.
Making simple code descriptions is as hard as making simple code. I believe a great programmer should be great at both.