【译】求你不要再写没用的提交信息了
开始尝试优化你的 Git 提交信息吧
我们都看到过的
你在一个项目中使用 Git 作为版本控制。
当你做完了一次修改之后,你想要尽快更新你的分支。
所以你打开了终端,输入了下面这些命令,完成了一次远端分支的更新。
git add .
git commit -m "added new feature"
git push
然后你做了一些自测,发现了一个新鲜的 bug。问题不大,你很轻松的就解决掉了这个 bug,现在你需要把新的代码再次提交到远程分支,于是你很熟练的使用起 Git 命令。
git add .
git commit -m "fix bug"
git push
你几乎每天都在重复做着这样的事情,当你打开 Git log 时,你会发现它长成了这个样子。
git log
到目前为止,一切看上去对你来说都还不错。毕竟你很熟悉你的代码仓库,即使不需要提交信息的提醒,你也知道每次修改都是在进行了哪些操作。
存在的问题
过了几个月,其他的开发者浏览了你过去的修改,他们想要尝试更深入的理解关于你所做的修改的一些细节问题,但是你的提交信息并不具备描述性,他们也就无法从中获取任何有用的信息。
无奈之下,他们只能挨个查看每次提交的不同,然而即使这么做了,他们也还是不能很明确的知道你在开发过程中一些选择的理由和你的一些思考。
由于软件开发是一个协作的过程中,所以人们总是会使用 git blame
操作来查看是谁对代码做了修改,并且会问你一些关于代码的问题。但是距离你写这段代码已经过去很长时间了,你的印象也比较模糊。当你查看你的提交时,你发现自己很难说出当时为什么要这么写,以及其中的一些逻辑细节。
你给同事发送了一个悲伤的表情,并且告诉他们,你没有办法给他们提供更多的信息。
书写优秀的提交信息
希望通过上面的故事,你已经知道了为什么要编写良好的、信息丰富的 Git 提交信息:
在软件工程这样需要协作的领域中,它可以帮助我们快速理解上下文。理想情况下,Git 提交信息需要由三部分组成:主题、正文和结语。
主题
主题需要是一句话来概括你提交内容所涉及的修改。它需要是祈使时态,以大写字母开头,结尾没有句号,并且最好小于50个字。
一个好的主题格式应该是像“This commit will …”这样的。好的提交信息也应该是一个比较完整的句子。“add new neural network model to back-end”。
而不好的提交信息就不是一个完整描述的句子,比如最常见的“fix bug”。
正文
正文需要包含你要传达的信息,让其他人在其中能够了解更多关于这次修改的细节。对于一些比较修改的修改,比如改动了一个变量类型,你可能不需要写正文,主题就足够描述这次修改的内容了。
在正文中,你应该更详细的描述这次修改中的一些细节问题,并且解释你所做的事情的前因后果。
你可以解释为什么要做出这个修改,为什么用这种特殊的方式来实现,或者其他你觉得能够帮助其他人理解你的修改过程的信息。
注意不要重复描述代码中显而易见的逻辑,正文也不是让你一行一行的解释代码,大家更加关注的是代码中不容易看出来的更深层的一些细节问题。我们的最终目标是为这次的修改提供有效的上下文信息,即更改主要的动机和目标。
结束语
最后,结束语应该出现在你的提交信息的最后一行。
你可以在这里提供一些关于此次修改的元数据,比如 JIRA 号,GitHub issue 号,合作者姓名,和附加信息的链接。
这有助于将你的修改的相关重要信息链接在一起。
原文链接
https://medium.com/better-programming/stop-writing-bad-commit-messages-8df79517177d
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- [前端] 设定为disabled的表单域值不能被提交
- 工厂方法模式
- 原创 | 这道题codeforces的简单题差点做了我一下午,你能解出来吗?
- OpenCV4 部署DeepLabv3+模型
- 使用OpenCV实现哈哈镜效果
- 如何使用OpenCV在Python中访问IP摄像头
- 分享我学习Pandas使用的资料,可能是新手入门Pandas最好的教程!
- 原创 | Git入门教程,详解Git文件的四大状态
- 原创 | ACMer不得不会的线段树,究竟是种怎样的数据结构?
- dplyr包summarize的使用
- Mysql的binlog和relay-log到底长啥样?
- 原创 | matplotlib绘图教程,设置标签与图例
- 原创 | 从抽象类开始,详解责任链模式
- 开发一个渐进式Web应用程序(PWA)前都需要了解什么?
- 知识图谱入门(二)