你还在用文言文写 git/svn log 吗? 兄弟们,要写好log啊!-原创手记-慕课网

我发现, 大部分的中国的程序员, 最弱的地方, 在于语言表达能力不好.

语文水平堪忧. (体育老师表示躺枪)
英语水平堪忧.

今天我想说一下, Git, SVN, CVS.. 这些代码管理系统的log应该怎么写.

log的作用: 给作者看的! 不是给别人看的!

是给我们程序员看的。让你可以轻易回到过去
10%的几率是其他人看.
90%的几率是你自己看.

所以, 写好log就是善待我们自己啊!!!

做程序员，必须会表达

好的程序员必须口才好
好的程序员不是憋闷的人。
好的程序员，必须擅长跟人沟通。

程序员也要正常说话, 不要使用你的文言文!

中⽂语法：主语 + 谓语 + 宾语 : “我写了代码。”
在git/svn log 中，越详细越好！宁可啰嗦，不要简略
“解决了bug 141: 登陆页面无法正常显示。”

绝对不要谓语后置, 例如: bug解决, 功能实现, XX模块完成. 这是文言文啊亲!

绝对不要写这样的：

宾语 + 谓语。 “BUG解决。”
写的过于笼统。 “haha”
不知所云。 “js2cofee”, “DS_Store”

做好你的email

下面以 git 为例:

Author: xiaowang <wangmoumou@siwei.tech>
- 应该是 (中文名字) + 正确的EMAIL：
- 小王 <wangmoumou@siwei.tech>
- 修改起来很简单： 在当前目录下：

 # vim .git/config
 [user]
   name = 小王
   email = wang@abc.com

下面是我搜集到的各种例子.

太含混的log:


commit d10104b974e22fc12e1d969bb8905497cc419d
Author: xiaowang <a@b.com>
Date:   Tue April 28 17:21:31 2018 +0800

多选图片上传

读者问: 这个功能是做好了, 还是没做好?

没有说明在哪里改动:


commit d10104b974e22fc12e1d969bb8905497cc419d
Author: xiaowang <a@b.com>
Date:   Tue April 28 17:21:31 2018 +0800

增加提示错误

是否应该叫“在XX页面中，增加了出错时提示信息？”

不要把git log当成涂鸦.


commit d10104b974e22fc12e1d969bb8905497cc419d
Author: xiaowang <a@b.com>
Date:   Tue April 28 17:21:31 2018 +0800

老王给了小王致命一击.

(故事背景是: 每周例会上, 老王拿出小王做的反面教程给大家上课. )

点评: 不要把工作中的花絮放到 git log 中! git log不是涂鸦啊亲!
但是逗比精神值得表扬!

是做完了还是没做完?


commit d10104b974e22fc12e1d969bb8905497cc419d
Author: xiaowang <a@b.com>
Date:   Tue April 28 17:21:31 2018 +0800

打开广告页面

“广告页面”仅仅是个模块，这个模块是做好了，还是没做
好？


commit d10104b974e22fc12e1d969bb8905497cc419d
Author: xiaowang <a@b.com>
Date:   Tue April 28 17:21:31 2018 +0800

sign_in 适配android

如果sign_in 是个页面的话, 我们应该使用中文名称，例如
“登陆页面做好了安卓适配”


commit d10104b974e22fc12e1d969bb8905497cc419d
Author: xiaowang <a@b.com>
Date:   Tue April 28 17:21:31 2018 +0800

细节修改

修改哪个页面的细节？应该改成:
“调整了XX页面的XX底纹，XX边框”

用文言文写log


commit d10104b974e22fc12e1d969bb8905497cc419d
Author: xiaowang <a@b.com>
Date:   Tue April 28 17:21:31 2018 +0800

stage 数据请求

“从staging服务器获取数据”？
还是啥意思？现代生活中有人这么说话吗? 不要用文言文说话!

连续出现N个 log相同的 commit


commit d1010xxx1111111111111111111111111111
Author: xiaowang <a@b.com>
Date:   Tue April 28 17:21:31 2018 +0800

js2coffee

commit d1010xxx2222222222222222222222222222
Author: xiaowang <a@b.com>
Date:   Tue April 27 17:21:31 2018 +0800

js2coffee

commit d1010xxx333333333333333333333333333
Author: xiaowang <a@b.com>
Date:   Tue April 26 17:21:31 2018 +0800

js2coffee

背景说明: js2coffee 是一个js工具,把javascript代码转换成 coffee代码. 所以,这里小王用了3个commit来完成这个工作. 但是, 要注意: 要写的详细一些! 否则我修改了100个页面, 怎么知道哪些页面是第一个 commit ,哪些页面是第二个 commit中做的?

应该改成:
“把XX页面的JS替换成了coffee”?

不说解决的是哪个bug. 只是笼统的几个字: 解决bug


commit d10104b974e22fc12e1d969bb8905497cc419d
Author: xiaowang <a@b.com>
Date:   Tue April 28 17:21:31 2018 +0800

调bug.

调了哪个BUG? 调整好了吗？

提交了不该提交的文件,还写到了log中.


commit d10104b974e22fc12e1d969bb8905497cc419d
Author: xiaowang <a@b.com>
Date:   Tue April 28 17:21:31 2018 +0800

DS_Store

啥意思? (熟悉mac的朋友,知道这是mac下编辑器产生的临时文件, 但是如果我搞出一堆 .swp, .swo 文件呢? )

结语

Log 是非常重要的东西, 平时用的少, 关键时刻回滚时,作用就体现出来了. 如果我要回滚, 首先想到的是 tag 和某个精准的 log. 如果满目看到的都是这个, 就没法回滚了. 除此之外, 规范的,详尽的log 是每个人都喜欢的. 没有人喜欢短句子的log .

希望大家每个人的log,都是能让其他人看懂的正常话. 下面，就是我在目前的项目组随意找的log，写的很详细，让人一年后都可以知道这个commit是干嘛的:

正常的log

你还在用文言文写 git/svn log 吗? 兄弟们,要写好log啊!原创