阅读 18424

从一件小事聊聊软件工程师的自我修养 | 掘金年度征文

思考:如果让你制定代码提交规范(Git工具),你会怎么做?

被忽略的细节

代码的提交信息是开发中一个很小的细节,由于它本身对代码运行本身不造成任何影响,主要作用在于方便查找、回退代码,所以很容易被开发者忽略。 但是它的意义就像项目文档、注释一样,是高质量项目必备的内容,好的提交信息不仅能帮助开发者快速找到指定版本的代码,同时节体现的也是开发者的习惯和意识。

这篇文章想和大家聊聊这个小小的细节和软件工程师(以下简称工程师)的修养,或许能给那些初入职场或处于职场上升瓶颈期的读者一些启发。

我们现在的项目的代码提交信息比较乱,所以很有必要建立一个代码提交规范。

下面就以3个不同工程师的处理方式来聊聊工作中的自我修养。

普通工程师

除非做过类似的工作,不然接到任务的第一件事一般是打开浏览器搜索“代码提交规范”之类的关键字,会发现相关结果很多。通过一番整理,得到下面的信息:

提交信息的编写格式

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

type:提交类型,可选值如下
* work: 开发中(work in progress)
* feature:新功能(new feature)
* fix:修补bug(fix bug)
* doc:文档(documentation changes)
* style: 格式(change code format)
* refactor:重构(modify code but not feature)
* test:增加测试(test code)
* chore:构建过程或辅助工具的变动(changes don't modify src and test files, only config or tasks)
scope:
用于说明 commit影响的范围,比如数据层、控制层、视图层等等,视项目不同而不同。
subject:commit 目的的简短描述。
body: 对本次 commit 的详细描述
footer: 描述一些特殊情况,不兼容变动和issue关闭。
复制代码

编写提交信息的工具

比如Commitizen,基本操作如下:

# 安装命令行工具
npm install -g commitizen

# 安装依赖
commitizen init cz-conventional-changelog --save --save-exact

# 通过扩展命令提交
git add .
git cz
复制代码

把上面的编写格式整理成文档,然后在项目中安装依赖试用以下,任务完成~

进一步思考

但是这只是做为普通工程师的标准,优秀工程师该怎么思考呢?

优秀的工程师和普通工程师的区别在于会反思工作并主动改进。也就是说不只满足把事情做完,而是主动把事情做好。 把事情做好大致有两种:

  1. 别人都能做的,但是你做得和别人不一样。
  2. 别人不能做的但你能做。

显然制定提交规范属于第一种情况,所以优秀的工程师会进一步思考。

优秀工程师

目前的方案有没有可改善的地方?

编写格式

每次提交的信息需要编写的内容非常多,如果每次提交个代码像写篇小作文一样麻烦,必然会引起反感。 这就好比本来开车上班路上时间不到半个小时,但是现在要求低碳出行只能骑自行车要1个小时,这种规定的可行性就很低了。 所以精简:

  1. 当文件路径较长或者数量较多时scope会变得很长,影响查看subject。而且修改的文件(夹)名称也可以在查询具体提交记录的时候查找出来。更麻烦的是如果提交的时候漏写或写错了还会起反作用,所以省略。
  2. body和footer都属于对提交的详细描述,合并成可选项description。

提交工具

git cz命令虽然可以替代git commit命令来提交代码,但是它的有工程师不使用git cz而仍然使用git commit命令来提交代码则校验就会失效。 所以需要一个校验工具来保证我们的规范有效的执行,至于工具git早已经为我们准备好了——钩子。钩子类似于web组件的生命周期,可以在执行某些操作前后触发对应的shell脚本。与git commit命令相关的钩子有4个,按顺序分别是:

  • pre-commit。提交前触发,不接收参数,可以执行一些文件校验的工作。
  • prepare-commit-msg。提交前触发,接收消息参数,用于在提交之前附加一些内容。
  • commit-msg。提交前触发,可接收消息参数,用于检查提交消息是否符合规范。
  • post-commit。提交后触发,可执行自动推送、部署代码等操作。

这里我们选择commit-msg来实现,对应的脚本会像下面的样子:

#!/bin/sh

if grep -Eq "^(work|feature|fix|refactor|doc|test|chore|style|revert):\s*\w+" "$1"; then
  exit 0
else
  echo "Please format your commit message as follow:"
  echo "<type>:<title>"
  echo "<description>(optional)"
  exit 1
fi
复制代码

目前的方案有没有可以补充的地方?

形成规范

规范就像是制度,好的制度不仅需要制定者花心思去设计,更需要执行者知晓和配合。 所以有了文档和工具之后需要考虑的另一件事就是在团队内部推广。 推广的方式常用的有做个PPT开会培训一下,或者把资料放到团队的wiki上提醒大家查看,这里就不详述了。

再进一步

到了这一步,任务不仅做完了,而且也算是做好了。 但要实现个人的最大提升,优秀还不够,必须卓越。 所以除了把事情做好之外,还应该考虑将它最大价值化。

卓越工程师

再回到例子中,这个解决方案有没有可能用于其它团队/场景?

通用性

编写格式这一块基本上没有太多问题,但是提交工具会成为一个较大的障碍。Node.js通常只是前端团队的工具。如果要在其它团队中推广使用,学习成本不说,还会在项目中引入额外的依赖,可操作性并不强。

那是不是也要针对其它开发语言的项目去找合适的解决方案?这当然可以但不见得是最好的方式,因为时间成本太高,最好的方式是找到一个通用解决方案。

还是钩子

其实这个方案git早已经为我们提供好,还是之前用到的钩子。虽然commitizen这类Node.js模块不是跨语言的解决方案,但是其采用按步骤给出提示语,然后由用户输入的交互方式,对于不熟悉规范的人来说还是比较好的。所以我们可以在钩子脚本中沿用这种形式。

但对于熟悉规范的开发者来说可能希望直接使用git commit命令一次性提交,所以还加入一些校验——对于不符合规范的提交信息给出交互提示,引导开发者按步骤完成提交信息。由于脚本内容较长,这里就不贴出来了,感兴趣的读者可以去文末的仓库地址中查看。

完善

如果要做得更完美一些可以使用git提供的template功能,具体使用可以查看文末提供的仓库地址。

总结

工作态度决定了工程师的潜力,思考维度决定了工程师能力的天花板(当然这句话在别的岗位也可能通用)。

制定提交规范虽然只是一件很小的事,但是可以从中总结出不同级别工程师在这两个方面的差异:

普通工程师 优秀工程师 卓越工程师
工作态度 公司安排什么就做什么、学什么,缺乏主动意识。 能完成公司安排的任务,有时候还会超预期完成,同时在工作之余会利用时间学习。 不仅能常常超预期完成公司的任务,同时还会主动思考团队、产品现有的问题或可以改进的地方并给自己安排任务
思考维度 单一、点状的。只关注任务本身,只考虑如何完成任务 线性、纵向的。会思考任务背后的目标,以及怎样才能更好的达目标而不仅是完成任务 网状,全局的。切换身份思考,让任务成果对组织产生最大价值

如果您觉得这篇文章对您有帮助请点赞,感谢阅读~


参考文章:

提交规范仓库地址:github.com/yalishizhud…


我的新书《了不起的JavaScript工程师:从前端到全端高级进阶》已经上架,获得了阮一峰老师等众多技术专家推荐,希望能帮助更多前端工程师一起成长提升,拥有全面能力和全局视野,成为了不起的JavaScript工程师!

关注下面的标签,发现更多相似文章
评论