Please keep code descriptions simple | AksDev
Please keep code descriptions simple
Posted on 2026-06-23 by Akseli Lahtinen<br>Just something I experience more and more these days.
Just something I experience more and more these days.
When it comes to reviewing code, the descriptions, commits and such can be massive blast of information: Full of extraneous details depicting what was changed. The main point is why was something changed. And often in only one huge commit with massive diffs.
I'm sorry but my poor ADHD brain can't take this very well. I don't want to read a novel. Usually blurbs of text are fine: Extraneous detail I can ask about if I need to know.
So this is my plea, from pure accessibility standpoint, to keep commit messages, merge request descriptions and code comments clear, to the point, need-to-know basis. Do not explain what, but why. Usually the code itself is enough to tell rest of the story. If not, I will ask questions. That's why it's a review.
It's easy to think that having huge description with all and everything is the way to go, but it will just make it slower for people like me to review it. I can barely concentrate already..
Then commits should always be atomic, especially during merge review. Use git amend to make small changes. Before merging, rebase and clean up, or squash. But try your best keep commits atomic: changes that can stand alone.
(Note that this is not aimed at any specific individual, I just finally had brains to write this post since I was reminded of the topic.)
If you use LLM tools, please still write comments, descriptions, commit messages etc. yourself. It helps you to understand whats going on, and it's more accessible for me to review. (Or better yet, try to avoid these tools if you can. I don't think anyone actually needs them. You're good enough without, I promise!)
Tags
personal
programming
git
ADHD
kde
Webmentions
Have you written a response to this post? Send me the URL!
Send Webmention!
Can't load webmentions without JavaScript, sorry!
FediFeed - My toots!
FediFeed requires Javascript, sorry!
Fun facts!
Source code!