Please keep code descriptions simple

请保持代码描述简洁

Posted on 2026-06-23 by Akseli Lahtinen 发布于 2026 年 6 月 23 日，作者：Akseli Lahtinen

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. 这是我最近越来越常遇到的情况。在进行代码审查时，描述、提交信息等往往包含海量信息：充斥着描述“改了什么”的无关细节。但重点应该是“为什么要改”。而且这些内容往往被塞进一个包含巨大差异（diff）的单一提交中。

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 accessibility-ish(?) 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. 抱歉，我那患有 ADHD 的大脑实在难以消化这些。我不想读小说。通常简短的文字就足够了：如果我需要了解无关细节，我会主动询问。因此，我从某种“无障碍”（accessibility-ish）的角度恳请大家：保持提交信息、合并请求描述和代码注释清晰、切中要点，仅提供必要信息。不要解释“是什么”，而要解释“为什么”。

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.) 此外，提交应该始终保持原子性，特别是在合并审查期间。使用 git amend 来进行小幅修改。在合并之前，进行变基（rebase）清理，或者压缩（squash）提交。请尽力保持提交的原子性：即每个提交都是可以独立存在的变更。（注：本文并非针对任何特定个人，只是因为被提醒了这个话题，我终于有精力写下这篇文章。）

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!) 如果你使用大语言模型（LLM）工具，请务必亲自撰写注释、描述和提交信息等。这有助于你理解代码逻辑，也让我更容易进行审查。（或者更好的是，如果可以的话，尽量避免使用这些工具。我不认为真的有人需要它们。我保证，没有它们你一样很棒！）

edit: Seems people are upset about me mentioning accessiblity there. I do not know what is the best way to describe it. But you can just ignore this blog post if it annoys you. 编辑：似乎人们对我提到“无障碍”一词感到不满。我不知道该用什么词来描述最合适。但如果这篇文章让你感到困扰，你可以直接忽略它。