代码注释规范

代码注释在程序软件中是非常重要的一部分，代码注释总体来讲分为三种注释：文件头注释、函数头注释及行注释，行注释就不多说了，这里重点聊文件头注释和函数头注释，以下是以C语言为例的，其他语言也都一样：

1. 文件头注释:

每个新生成的文件，需要添加一个文件头，最主要的写明谁在什么时间为什么创建：版权声明, 文件名称, 创建者, 创建日期, 文件描述, 历史记录 。 如果文件发生了比较大的改动要在历史记录中添加一条，描述清楚谁在什么时间修改了什么以及原因。
/*
* 版权声明: 暂无
* 文件名称 : mfptp_evcb.c
* 创建者 : 许亚飞
* 创建日期: 2015/04/20
* 文件描述: 本文件主要存放mfptp协议中libev事件的callback函数
* 历史记录: 无
*/

2. 函数头注释：

每个新生成的函数，需要添加一个函数头，主要是描述清楚：函数的功能，输入(参数、全局变量)、输出(返回值、输出参数、修改的全局变量、磁盘文件等)、修改(生成函数、修改函数都要新生成一条谁在什么时间修改了什么，以及因为什么修改)
/*
* 名 称: mfptp_pack_login_ok
* 功 能: 生成登录认证成功的应答消息帧
* 参 数: buf, 存储消息帧的首地址
* 返 回 值: 应答消息帧的长度
* 修 改: 新生成函数 许亚飞 2015/5/7
*/

编码规范的目标是：让代码更容易被人看懂，让工具更容易处理，用来减轻负担，而不是相反。

文件名，有几个作用:
1. 如果你起的文件名比较难理解，可以把全称或者解释写在这里。例如evcb.h第一次看到可能没人懂这文件是干啥的，如果文件名部分写上evcb.h/event callback或者在文件描述里写上，大家一下就能猜到这个文件大概是干嘛的。
2. 提醒大家如果修改了文件名字，需要更新文件头的历史记录部分，将原来旧的文件名字记录下来，这样即使团队开发中某个人更改了文件的名字给其他人造成的困惑也会减弱一些
3. 方便自动化脚本处理。比方任务交接时可以方便的拉出某个人创建的所有文件，接替者可以仔细查看是否达到可接手程度。

创建日期可以帮助大家回想当时的背景，可以以此线索查找其他相关文件、函数。

创建者可以帮助大家找到当年是谁写的、谁建的，定位问题时可以向他求助，出了问题可以回溯。

注释代码的程度是和团队的知识结构和成熟度相关的，一般开发团队的共识分为两部分，一部分是已经固化在文档中且团队成员都知道的，一部分是在大家各自头脑中还没有被文档化的。
如果团队成员人人都知道的可以不必注释的，40%的代码注释率一般认为是比较好的，但不是绝对的，比如简单的操作没有注释也是可以接受的。

注释在开发中也是一个问题，一般几个原因造成，1 注释是有歧义的 2 代码修改了注释没有更新 3. 知识结构不同，即使是汉语注释的也看不懂

编码规范的目标是，让代码更容易被人看懂， 让工具更容易处理