数据库编程之注释规范

1.6 注释规范
注释规范是判断一个开发人员优劣和成熟度的重要指标。一个优秀的研发人员必然是经过深思熟虑然后才洋洋洒洒妙笔生花的，注释的书写体现了一个人思考问题的全过程和步骤；话又说回来，就算代码写的烂，只要注释写的好，至少也会给人以良好的感觉；同时也能造福后人，不是么？呵呵。

规则1.6. 1

一般情况下，源程序有效注释量必须在30% 左右。

说明：注释的原则是有助于对程序阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言须准确、易懂、简洁、精炼。

规则1.6. 2

统一文件头的注释.

主要是对相关过程、函数进行功能性描述、修订记录、以及入参出参说明

对存储过程、函数的任何修改，都需要在注释后添加修改人、修改日期及修改原因等修订说明。

/***********************************************************

名称: sp_xxx

功能描述：

修订记录：

版本号 编辑时间 编辑人 修改描述

1.0.0 2010-01-01 John 1 、创建此存储过程

1.0.1 2010-02-01 Sandy 2 、增加传入参数

入参出参描述：

iparameter1 IN VARCHAR2(20) 传入参数1

iparameter2 IN VARCHAR2(20) 传入参数2

iparameter1 OUT VARCHAR2(20) 传入参数1

iparameter2 OUT VARCHAR2(20) 传入参数2

返回值描述：( 主要针对函数)

0 – Success

1 – normal fail

***********************************************************/

规则1.6. 3

所有变量定义需要加注释，说明该变量的用途和含义。

规则1.6. 4

注释内容要清晰、明了、含义准确，防止注释二义性

在代码的功能、意图层次上进行注释，提供有用、额外的信息。

避免在一行代码或表达式的中间插入注释。

尽量使用”– ”进行注释；行尾注释须使用”– ”。

规则1.6. 5

对程序分支必须书写注释。

说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。

在程序块的结束行右方加注释，以表明程序块结束。

规则1.6. 6

注释应与其描述的代码相似，对代码注释应放在其上方或右方( 对单条语句的注释) 相近位置，不可放在下面。

注释与所描述的内容进行同样的缩排。

注释上面的代码应空行隔开。

建议1.6. 7

注释用中文书写

有一次，同事写了一个900 行的存储过程，里面定义了十几个游标以进行遍历，这个存储过程缺乏注释，执行一次居然要一天一夜，已经达到了无法容忍的地步。

因为缺乏注释，我花了整整一天的时间来对该存储过程进行分析，然后用了半天时间来进行改写和调试。

其实很简单定义，我定义了一些对应的临时表，把游标遍历替换成SQL 的集合操作，把整个的一个大事务分割成若干小事务，只是修改了部分代码，结果执行时间就变成了短短的3 分钟。

当然游标也并非不可触及的，既然存在就有他存在的理由。

【编辑推荐】

1. 数据库编程之书写规范
2. 在MySQL数据库中如何来复位根用户的密码
3. 带你深入了解数据库设计中的英文术语表