技术写作与文档2018juffalow.com
写好 Git 提交信息
Write good git commit messages
导读
这篇讨论如何写出好的 git commit message，核心是让提交信息像故事一样清晰、原子化、可读，从而帮助读者理解代码决策。对写作者来说，它提供了关于叙事结构、动词选择、读者视角和规范反思的通用写作启发。
可以直接用的写作要点
- 01
把每一次提交或每一段内容写成独立、完整的小单元，让读者能按顺序理解你的决策脉络。
- 02
用精确的动词开头，但动词应描述“作品实现了什么”，而不是只报告“作者做了什么”。
- 03
写作规范要服务于可读性，避免为了形式而牺牲表达的灵活性。
- 04
保持简洁和原子化：一次只做一件事，减少读者的理解成本。
HN 评论精选
好的提交信息像故事一样帮助理解决策，且写干净提交成本低、收益高。
写好提交信息，在我看来是区分“能写出好代码的开发者”和“能产出高质量工作的开发者”的关键之一。git log 是开源（其实闭源也一样）项目的主要入口之一，顺着读就像在读一个故事，能帮你理解当初的决策。想象你要二分排查两个项目：一个提交干净、原子、描述清晰；另一个 git log 像这样（附链接）。我知道我想调试哪一个。这也是我极不喜欢 merge commit 的主要原因：它们让 git log 极难读。好在写干净的提交极其容易，不像文档和测试那样是额外工作（其实更省事），也不用随代码变化持续维护。它是你能立刻改进开发习惯、并显著提升生活质量的一件事。你会在这样做的时候抓到 bug！（写原子提交的小技巧：用 `git add -p` 来暂存补丁块。）
scrollaway查看英文原文
Writing good commit messages is one of those things that IMO make the difference between a dev who produces good code, and a dev who produces high quality work in general. The git log is one of the main entry points to an open source (or closed source, in fact) project. Following them tells a story, and can help you understand decisions made. Imagine you have two projects to bisect. One of them has clean, atomic and descriptive commits. The other has a git log that looks like this: https://github.com/pypa/pipenv/commits/master?after=d4d54eeb39ef45a9b68c78b8fc8f66c3f5396691+1154 I know which one I'd want to debug. This is also the primary reason why I highly dislike merge commits: They make git logs extremely unreadable. The thing is that writing clean commits is something that is extremely easy to do. Unlike docs and tests, it's not more work (it's less, in fact) and it's not something to continuously maintain as the code changes. It's an immediate improvement you can make to your development habits that will have a consequential improvement to your QOL. You will catch bugs doing this! (Tip when writing atomic commits: Use `git add -p`. That lets you stage patch hunks.)
用一组精确、分类清晰的动词来统一提交信息的开头。
我用下面这套约定来开头提交主题（来自 HN 上另一个类似讨论）：Add=新增能力（功能、测试、依赖）；Cut=移除能力；Fix=修复问题（bug、笔误、意外、错误陈述）；Bump=提升版本（如依赖）；Make=改构建流程、工具或基础设施；Start=开始做某事（如创建功能开关）；Stop=停止做某事（如移除功能开关）；Refactor=必须只是重构的代码改动；Reformat=格式化重构（如去掉空白）；Optimize=性能重构（如加速）；Document=文档重构（如帮助文件）。
navinsylvester查看英文原文
I use the following convention to start the subject of commit(posted by someone in a similar HN thread): Add = Create a capability e.g. feature, test, dependency. Cut = Remove a capability e.g. feature, test, dependency. Fix = Fix an issue e.g. bug, typo, accident, misstatement. Bump = Increase the version of something e.g. dependency. Make = Change the build process, or tooling, or infra. Start = Begin doing something; e.g. create a feature flag. Stop = End doing something; e.g. remove a feature flag. Refactor = A code change that MUST be just a refactoring. Reformat = Refactor of formatting, e.g. omit whitespace. Optimize = Refactor of performance, e.g. speed up code. Document = Refactor of documentation, e.g. help files.
质疑提交信息规范的规定性，主张用实证方法检验其实际效果。
这类规定总让我觉得是软件开发人员刻板印象里的那种过分讲究。我希望能看到有人用描述性而非规定性的方法来对待提交信息，甚至用科学方法去测量这些做法是否有超出个人轶事偏好的具体可测效果。规定提交信息长什么样，其实隐含地规定了提交能长什么样，把灵活的工具变得不那么灵活。对很多人来说，缺乏灵活性可以是个优点……但它是否真的有助于开发，是个实证问题，而我并没听说有人在测量这些。本着 Fred Brooks“没有银弹”的精神，我怀疑在代码注释、代码文档和工单系统之外，git 提交还能增加多少价值。
BlackFly查看英文原文
These sorts of prescriptions always strike me as the sort of fastidiousness that some software developer types are stereotyped with. Just once I would like to read someone that takes a descriptivist approach to commit messages instead of a prescriptivist approach. I would prefer even a scientific approach where someone sets out to measure if these sorts of measures have a concrete measurable effect beyond people's anecdotal preferences. Prescribing what a commit message can look like implicitly prescribes what a commit can look like and that turns a flexible tool into a less flexible one. For many people, lack of flexibility can be a feature... but it is an empirical question on whether or not if it aids development and I am not really aware of anyone trying to measure these things. In the spirit of "No silver bullet," by Fred Brooks, I am skeptical that between the code comments, the code documentation, and the ticketing system that the git commits are adding much.
动词应描述程序因改动获得的能力，而非作者的动作。
我的看法是：这些不算好的提交信息。动词不该描述你做了什么，否则永远只会是“添加”“修改”或“修复”。动词应该描述因为这个改动，程序能做什么。例如“Check server fingerprint”，而不是“Add server fingerprint check”。我们本来就知道你改动或添加了东西，这可是 git 提交。
jimmytucson查看英文原文
My take: these aren’t good commit messages. The verb isn’t supposed to be what you did, otherwise it would always be “add” or “change” or “fix”. The verb is supposed to be what the program does thanks to this change. E.g. “Check server fingerprint”, not “Add server fingerprint check”. We already know you changed or added something, it’s a git commit.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选