技术写作与文档2020altcampus.io
如何写好 Git 提交信息
How to write good Git commit messages
导读
这篇短文讲如何写出好的 Git commit message（提交说明），本质上是关于一种被低估的实用写作：用一两句话让未来的读者（同事、审查者、几个月后的自己）快速理解一次改动的意图。评论区有实用补充，也有尖锐的反面意见：很多人认为没人会读旧提交，不必过度投入。这种分歧本身值得写作者思考：写作的价值取决于读者和使用场景。
可以直接用的写作要点
- 01
标题用简短祈使句说明这次改动做了什么，正文再交代为什么这样做、影响是什么，而不是机械罗列改了哪几行。
- 02
一次提交只包含一件相关的改动，让每条提交记录能独立被读懂；否则再好的说明也会失效。
- 03
动笔前先问读者是谁、在什么场景下读：是代码评审、排查问题，还是生成变更日志；据此决定写多详细。
- 04
别把写说明当成负担，也别追求完美格式；清晰传达意图比套用模板更重要。
HN 评论精选
反方观点：多数项目没人读历史提交，不必把它当成硬性最佳实践或自我评价标准。
我在 20 个商业代码库里工作了十年，觉得写好提交说明根本不重要——没人会读旧提交，真相就是代码现在在做什么，它怎么变成这样并不重要。当然总有人说自己经常翻历史、长段落背景很有用，但对 95% 的开发者或项目并非如此，所以我不推荐花时间学这种“最佳实践”。有志向是好事，但如果有人看了这类文章就觉得自己是失败者或“差”开发者，那太可惜了。如果这对你个人有帮助，或者你在做开源、需要维护变更日志，那就尽管写。但对普通环境里的在职开发者来说，有太多更有影响力的技能值得花时间。
swanson查看英文原文
I've worked for 10 years across 20 different commercial codebases. None of this stuff about writing good commit messages really matters. No one reads old commits. The "truth" is what the current code is doing and it doesn't really matter how it got there. I'm sure someone will say "but I use the history ALL THE TIME to source dive and paragraphs of context are super helpful". This is not the case for 95% of developers or projects so I can't really endorse spending time learning this "best practice". It's fine to be aspirational, but it's such a shame if people see posts like this and think they are failures or "bad" developers or that this is a widespread practice. If it helps you personally or you have an open source project and you want to help with a changelog, knock yourself out. But there are so many more impactful skills to be learning or spending your time on if you're a working developer in a typical environment.
原子化提交是写好说明的前提，也让 git blame 这类追溯工具真正有用。
也许同样重要的是：确保同一次提交里的改动彼此相关。`git blame` 是个被严重低估的功能，原因可能是只有当你养成关注“每次提交放了什么”的习惯后，它的好处才会显现。但能直接从你正在看的那行代码跳到相关代码的上下文，是非常有价值的。
Vinnl查看英文原文
Maybe just as important: make sure the changes in a commit are related. `git blame` is a criminally underused feature, possibly because the benefits only become clear after you've had the discipline of paying attention to what goes in a commit. However, being able to pull up the context of related code right from the context of the line you're looking at [1] (from my post at [2]) can be very valuable. [1] https://vincenttunru.com/img/Commits-are-documentation/annotations.png [2] https://vincenttunru.com/Spend-effort-on-your-Git-commits/
低成本的写作规范往往最难推动，靠道理说服不如靠机制约束。
我在公司向所有团队推广过类似做法（我是其中一个团队的经理）。我以为这是不言而喻、常识性的轻松改进，却遭到强烈抵制，而且我推的版本比这些建议还基础！推荐和教练当然好，也应该继续做；但归根结底，在这件事上，你可能得一路往上找到一位“仁慈的独裁者”来强制规定标准。我很想单靠道理说服人，但借用学术界常见的一句话：“抵制之所以强烈，是因为利害太小。”
nogabebop23查看英文原文
I promoted something similar to all teams at my company (I'm a manager of one) and something that I thought was a no-brainer, common sense, easy win was met with very strong resistance - and mine was even more basic than these recommendations! It's great to recommend and we should keep coaching and mentoring but ultimately this is an area where I think you'd be better to go up the chain of command until you reach a benevolent dictator who can mandate criteria. I'd love to convince people based on the merits alone, but to paraphrase a common observation in academia "the resistance is high because the stakes are so low".
好的提交说明服务于三个层次：概览、细节与工单背景。
我常推荐给团队里开发者的另一个好资源是 chris.beams.io 那篇讲提交信息的文章。作为管理多个代码库的人，这套规范加上经过整理的压缩提交，让我能：（1）在高层面上理解每个提交做了什么；（2）需要时深入单个提交，细看具体改动；（3）查看与该改动相关的 JIRA 工单，这往往比前两点更有价值。
Vinnl查看英文原文
Maybe just as important: make sure the changes in a commit are related. `git blame` is a criminally underused feature, possibly because the benefits only become clear after you've had the discipline of paying attention to what goes in a commit. However, being able to pull up the context of related code right from the context of the line you're looking at [1] (from my post at [2]) can be very valuable. [1] https://vincenttunru.com/img/Commits-are-documentation/annotations.png [2] https://vincenttunru.com/Spend-effort-on-your-Git-commits/
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选