最近在使用Github时,发现Github for windows将注释分为Summary和Description两部分;而使用GitShell时没有分解成两部分,但是在Github网页上只显示Git注释的第一行。注释这种东西,无论语言的还是工具的,其实都没有强制执行的标准,常因人而异。但是若能统一,既能增强美感,也能有助于交流。因此上网查了下Git注释风格的文章,对比发现Fwolf的博客总结的很到位,引用如下:
可以先看看一些著名开源项目源代码管理系统当中的提交注释, 其中也有用 SVN 和 Bazaar 的, Apahe 的源码看不到 logview,可能是使用了 CVS 文件格式的原因:
结合其他参考文章,我总结 Git 的 推荐 注释风格如下:
-
第一行为对改动的简要总结,建议长度不超过 50,用语采用命令式而非过去式。
Vim 很贴心,在默认配置下,注释的第一行文字颜色是黄色, 超过 50 列之后就变成白色了。
-
第一行结尾不要英文的句号 . ,中文的就也不要 。 吧。
为啥?我给 rst2wp 提交的时候,对方也提出了这个要求 [1] [2] , 后来查了查,大概原因是,第一行被认为是一个“标题”,也会作为邮件标题, 而标题是不需要标点的。 上面那些开源项目也都遵守了这一规则。 不过也有 例外的 。
-
第二行为空行。
如果配置了自动发送邮件,那么第一行就用来做邮件标题, 第三行开始的内容是邮件正文, 第二行是分隔线,用于区分两者。
-
第三行开始,是对改动的详细介绍,可以是多行内容,建议每行长度不超过 72。
可以包括原因、做法、效果等很多内容,一切你认为与当前改动相关的。 为何是 72 长度呢?因为 git log 输出的时候能显示得比较好看, 前面 4 个空格作为缩进,后面留 4 个空格机动(英文按单词排版)。 Vim 的 gq 命令排版很方便。
一些项目还对这个部分的内容有特殊要求,比如加一些特定标签什么的。
-
建议全部英文,首字母大写。如果一定要用中文,请尽量使用 UTF-8 编码。
-
大项目中,可以用 module/submodule: 前缀作为第一行的开头, 前缀首字母不必大写。
前缀的冒号后面跟一个空格比较好看。 为了控制字符串长度,子模块名称可适当缩写,但应保持统一。
我以前喜欢在注释第一行加上 New: Add: Fix: 这样的前缀, 看来也是没有必要了。
Tips: 提交之前,用 git diff --check 可以检查有无空白字符错误, 比如行尾留有空白什么的。