技术英语 / 系统课时
写出清楚的 Commit Message
写出清楚的 Commit Message
提交信息的价值不在于把改动翻译成英文,而是让审查者一眼看出“做了什么、为什么做、影响哪里”。本节用一套可复用的动词与正文写法,把模糊的 update、fix bug 改成可检索、可追溯的提交记录。
学习目标
- 用准确的英文动词描述新增、修复、重构和移除操作
- 在标题中同时交代动作与对象,避免模糊表达
- 用正文补充改动原因、处理方式和影响范围
标题先写动作与对象
好的 Commit Message 标题通常从一个明确动作开始,再指出动作作用于什么对象。这里优先使用动词原形,例如 Add、Fix、Refactor、Remove,而不是只写 Updated、Changes 或 Bug fixed。
| 意图 | 推荐动词 | 示例 |
|---|---|---|
| 新增能力 | Add、Support、Allow |
Add CSV export for reports |
| 修复缺陷 | Fix、Prevent、Handle |
Fix token refresh after 401 |
| 调整内部实现 | Refactor、Extract、Simplify |
Refactor cache eviction logic |
| 删除旧能力 | Remove、Drop |
Remove legacy debug flag |
标题中的对象也必须具体。Update code 几乎没有检索价值,而 Update retry policy for API requests 能直接告诉审查者改动发生在哪里。
正文补上原因与影响
标题适合回答“做了什么”,正文则用于解释仅看 diff 不容易恢复的上下文。通常写清三个问题就够了:原来的问题是什么、这次为什么采用当前方案、哪些模块或行为会受到影响。
下面的提交正文把原因、处理方式和边界压缩在几行内:
Fix token refresh after 401
The client reused an expired refresh token after a 401 response.
Clear the cached token before retrying so authentication can recover.
This affects only the HTTP auth path; the API contract is unchanged.第一行可以单独出现在提交列表中;后面的正文解释了故障条件、修复动作以及未发生变化的接口边界。审查者即使几个月后再看到这条记录,也不必重新阅读全部代码才能理解当时的决定。
把模糊词换成可验证动作
Update、Change、Improve 并非错误,但它们经常隐藏了真正发生的动作。写完后可以问一句:只看这句话,别人能否判断代码实际增加、修复、删除还是重构了什么?
| 模糊写法 | 更清楚的写法 |
|---|---|
Update docs |
Document Redis startup requirement |
Fix bug |
Fix duplicate notifications after reconnect |
Change parser |
Allow parser to ignore empty trailing fields |
Improve cache |
Reduce cache lookups for repeated user IDs |
还要避免把标题写成实现过程的流水账。例如 Try another condition in loop 描述的是写代码时做过什么,而 Prevent duplicate retries after timeout 描述的是最终行为变化,后者更适合作为长期记录。
提交前检查信息是否够用
提交前可以快速检查三项:标题是否以明确动词说明最终动作,对象是否具体到模块或行为,正文是否只补充无法从标题直接得出的原因和影响。一个提交如果需要很长的标题才能解释清楚,也可能意味着它包含了多个彼此独立的改动。
Commit Message 不需要写成小型设计文档。让第一行负责定位改动,让正文留下关键决策与边界,就已经足以同时服务代码审查、git log 检索和后续故障追溯。