C/C++之Git注释风格

    最近在使用Github时，发现Github for windows将注释分为Summary和Description两部分；而使用GitShell时没有分解成两部分，但是在Github网页上只显示Git注释的第一行。注释这种东西，无论语言的还是工具的，其实都没有强制执行的标准，常因人而异。但是若能统一，既能增强美感，也能有助于交流。因此上网查了下Git注释风格的文章，对比发现Fwolf的博客总结的很到位，引用如下：

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

• Linux Kernel
• Apache HTTPD
• Mysql Server 5.6
• PHP
• Git

结合其他参考文章，我总结 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 可以检查有无空白字符错误， 比如行尾留有空白什么的。