注释规范

【规则-1】：所有变量定义都要加上注释，说明变量的用途及含义。

例：

create or replace procedure sp_sms_zone

as

… …

  v_city    number(2);        --监控信息变量

  v_db      number(2);        --数据库代码

  v_Total   number(10) :=0;   --发送总数

  v_Succ    number(10) :=0;   --成功数

  v_Fail    number(10) :=0;   --没有发送数

  v_Srl     number(10) ;      --记录流水

o_flag number;       --调用sp_send_query_sms返回的标识

… …

end sp_sms_zone;

/

【规则-2】：注释内容要清晰、明了，含义准确，防止注释二义性。

例：

正确：

ret_code out integer,--返回代码(0 成功 ,其它：错误,参见：错误代码定义)；

错误：

ret_code out integer,--返回代码

【规则-3】：对存储过程的任何修改，都需要在注释最后添加修改人、修改日期及修改原因等信息。

例：

/*

修改原因：修改积分兑换和积分转赠

修改人：***  

修改时间：2011-11-05

*/

【规则-4】：对程序分支必须书写注释。

例：

--如果为手机号码

if i_number_type = 0 then

begin

… …

end;

【规则-5】：在代码的功能、意图层次上进行注释，帮助维护人员理解代码。

例：

case rdm_type1

   when 1 then  --积分奖励

     ... ...

   when 2 then  --扣减(停用)

   ... ...

   when 3 then  --积分兑换

   ... ...

end case;

【规则-6】：代码注释应放在描述的代码上方或右方相近位置，不可放在下面。

例：

--查询转出用户的积分信息

SP_SCORE_QUERY(

   s_user_id,   --用户id

   rdm_city_id, --地市id

   … …

)

【规则-7】：注释与所描述的内容进行同样的缩排。

例：

--未达到可兑换标准

if v_score_change_flag=0 then

     --对于兑换类型为961的，取消1000分门限的限制。

     if rdm_type2 = 961  or rdm_type2 = 962 then

     end if;

end if;

【规则-8】：函数应对返回的代码进行详细描述。

例：

create or replace function fn_check_brand_package(

       i_package number,

       i_user_id number,

          i_brand_id number := 0,

          i_pay_mode number := 0 

) return number is

Result  number(1):=0;   --0表示没有限制 ,其他表示有品牌限制

… …

end fn_check_brand_package;

【规则-9】：在程序块的结束行右方加注释，以表示程序块结束。

例：

--未达到可兑换标准

if v_score_change_flag=0 then

… …

end if;--未达到可兑换标准处理结束

【规则-10】：统一文件头的注释。

例：

create or replace procedure sysmgmt.sp_encrypt3

(

       i_pwd            in   varchar2,

       o_new_pwd  out  varchar2,

       o_flag           out  number

) is    

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

功能描述：密码加密脚本，本存储过程用于把指定的明文密码转化为密文

参数描述：pwd：输入明文密码，

new_pwd：输出的密文，

o_flag：输出结果的状态(0：right，1：error)

修改历史：

    2005-12-28 ***，修改加密方式为密钥方式；

    2005-05-16 ***，修改加密算法；

2005-01-01 ***，创建脚本；

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

bl1          varchar(1);

       bl2          varchar(1);

BEGIN

… …

end;