技术英语 / 系统课时

写出清楚的 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 不容易恢复的上下文。通常写清三个问题就够了:原来的问题是什么、这次为什么采用当前方案、哪些模块或行为会受到影响。

下面的提交正文把原因、处理方式和边界压缩在几行内:

text
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 检索和后续故障追溯。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

写出清楚的 Commit Message

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通