Git commit 注释格式

Git 本身并没有硬性限制注释的格式,不过,对于多人参与的项目来说, 好的注释风格更加有利于团队合作。 即使是自己用,也应当坚持实用好的注释风格, 一来是对自己的工作历史负责,二来得以养成好的注释习惯。 虽然这里标题说的是 Git,其他源代码控制系统也可以参考的。

可以先看看一些著名开源项目源代码管理系统当中的提交注释, 其中也有用 SVN 和 Bazaar 的, Apahe 的源码看不到 logview,可能是使用了 CVS 文件格式的原因:

结合其他参考文章,我总结 Git 的 推荐 注释风格如下:

  1. 第一行为对改动的简要总结,建议长度不超过 50,用语采用命令式而非过去式。

    Vim 很贴心,在默认配置下,注释的第一行文字颜色是黄色, 超过 50 列之后就变成白色了。

  2. 第一行结尾不要英文的句号 . ,中文的就也不要 吧。

    为啥?我给 rst2wp 提交的时候,对方也提出了这个要求 [1] [2] , 后来查了查,大概原因是,第一行被认为是一个“标题”,也会作为邮件标题, 而标题是不需要标点的。 上面那些开源项目也都遵守了这一规则。 不过也有 例外的

  3. 第二行为空行。

    如果配置了自动发送邮件,那么第一行就用来做邮件标题, 第三行开始的内容是邮件正文, 第二行是分隔线,用于区分两者。

  4. 第三行开始,是对改动的详细介绍,可以是多行内容,建议每行长度不超过 72。

    可以包括原因、做法、效果等很多内容,一切你认为与当前改动相关的。 为何是 72 长度呢?因为 git log 输出的时候能显示得比较好看, 前面 4 个空格作为缩进,后面留 4 个空格机动(英文按单词排版)。 Vim 的 gq 命令排版很方便。

    一些项目还对这个部分的内容有特殊要求,比如加一些特定标签什么的。

  5. 建议全部英文,首字母大写。如果一定要用中文,请尽量使用 UTF-8 编码。

  6. 大项目中,可以用 module/submodule: 前缀作为第一行的开头, 前缀首字母不必大写。

    前缀的冒号后面跟一个空格比较好看。 为了控制字符串长度,子模块名称可适当缩写,但应保持统一。

我以前喜欢在注释第一行加上 New: Add: Fix: 这样的前缀, 看来也是没有必要了。

Tips: 提交之前,用 git diff --check 可以检查有无空白字符错误, 比如行尾留有空白什么的。

BTW,在使用 Git 或者其他 SCM 时,还应当避免下面这些做法:

  • 把 SCM 当做备份工具。

    SCM 是项目/代码管理工具,备份功能只是“福利”。 随意将未完成测试或临时的工作结果进行提交, 不仅破坏日志的“纯洁性”,还不利于日后的浏览、整理、汇总等工作。 在开源项目中这么做的话,没人会接受这种提交。 如果确实需要备份当前工作异地继续的话,可以采用这样的折衷方法:

    $ git commit                # 在本地进行提交
    $ git format-patch -n1      # 导出 Patch
                                # 这个 Patch 就是你的备份
    $ git am Path_To_Patch_File # 如果换了工作地点,导入 Patch
    $ git reset --mixed [hash]  # 撤销提交,保留更改,继续工作
  • 一个改动不一次提交完成。

    “提交”的概念是具有独立的功能、修正等作用。 小可以小到只修改一行,大可以到改动很多文件, 但划分的标准不变,一个提交就是解决一个问题的。

    对格式的修正,不应该和其他功能修补一起提交, 这种情况应该考虑使用 git add --editgit add -p 也可以用用,更复杂和强大一些。

  • 注释不清晰。

    比如只有“修正 BUG”、“改错”、“升级”等,没有其他内容,等于没说。

参考

新的广告交换、51.la统计和web标准

标题又有点风牛马不相及,不过还是有那么一点点关联的,再说了,一篇文章的内容相对广泛,不仅有利于SEO,而且还会给胡乱转载者以困惑,同时还不会干扰正常转载、引用的朋友,嘿嘿。

首先说今天我第一次见到的网站广告交换–BlogUpp,感觉很新颖,很方便,就顺手也弄了一个,放在右边的广告下面,感觉特点如下:

  1. 不用注册,直接输入网址,就得到一段代码,扔网站页面上就行了。
  2. 交换广告是竖向排列的两个,固定的大小和布局,至少目前没得选择,不过适合blog这种右边大条空白的情况。
  3. 加载的时候,先显示文字,然后加载图片,当然文字和图片都是从每个网站上攫取出来的,中文支持良好。
  4. 正常显示广告的情况下,一般是显示图片,鼠标滑过的时候,切换为文字内容,既用图片吸引了眼球,又能让读者根据文字内容来了解是否真的需要打开浏览,应该说这一点我觉得是它设计最好的地方。
  5. 提供两种形式的代码,一种是iframe另外一种是style+div,我鸡蛋里挑点骨头:第二种里面的target="_blank"这种用法是不符合w3c标准的。

之所以对w3c标准如此敏感,是因为下午刚刚为51.la统计代码无法通过w3c验证而头疼(验证的不是本blog的页面,选用dtd是XHTML 1.0 Strict)。先来看一下这段代码吧:

<script type="text/javascript" src="http://js.users.51.la/272422.js"></script>
<noscript><a href="http://www.51.la/?272422" target="_blank"><img alt="&#x6211;&#x8981;&#x5566;&#x514D;&#x8D39;&#x7EDF;&#x8BA1;" src="http://img.users.51.la/272422.asp" style="border:none" /></a></noscript>

w3c的validator一检查,错误就出来了,主要有两处,一处比较简单:

document type does not allow element "a" here; missing one of "p", "h1", "h2", "h3", "h4", "h5", "h6", "div", "pre", "address", "fieldset", "ins", "del" start-tag . 

就是说a不应该出现在这里,它属于inline元素,应该被包含在block元素中云云,img也是一样,解决方法是用p或者div元素来包含他们就可以了。

而第二个不兼容就比较棘手了:

there is no attribute "target" . 

也就是`target=”_blank”这种用法是标准不允许的,这个问题着实难解决了点。

有朋友说了,你不会用js来实现么?的确,网上有解决方式是先赋予a链接rel=xxx属性,然后用js判断属性再脚本运行时添加`target=”_blank”属性,或者直接用js打开脚本的也算一种方法。

可是各位,你们没有发现,这个链接是在<noscript>标签中么?这个标签中的代码只有在浏览器不支持js的时候才会显示,试问,在不支持js的浏览器中,刚才的js解决方案还能用么?

最终,我也没有更合适的解决方案,只有把`target=”_blank”去掉,然后在旁边注上一行字:

<noscript>
    <div>
        <a href="http://www.51.la/?272422">
            <img alt="&#x6211;&#x8981;&#x5566;&#x514D;&#x8D39;&#x7EDF;&#x8BA1;"
                src="http://img.users.51.la/272422.asp" style="border:none" />
            Tips: 在新窗口中打开链接,浏览更方便(点鼠标右键)。
        </a>
    </div>
</noscript>

我想,目前也只能用这种方式解决了吧,好在不支持js的浏览器、又是人在用的(非机器人),应该不多。

其实,51.la代码的兼容性之所以被发现,之所以不得不改,也不是我吹毛求疵,而是用了eclipse之后,它的语法检查给发现的(够强大的),实在是不习惯看到一对error和warning在下面待着,“被迫”修改代码使它们更加“标准”,我想这也是eclipse的一个优点吧。

PS: 在BlogUpp缩图中我网站的首页太难看了,一个图片也没有,hmm…,有没有好一点的wordpress两栏布局模板,突出文章内容的?偶也换换?

参考

Update @ 2008-05-12

看到妖精BlogUpp的上下布局给横过来了,猜测是自己手工改的,官网上好像没这个功能啊。。。