第三部分：注释规范[@more@] Normal 0 7.8 磅 0 2 false false false MicrosoftInternetExplorer4

代码必须做适量的注释，以便于理解和跟踪。

1. 通用规则

l 源代码应做适 量的注释，清晰地表述代码用途、适用范围、变更历史、处理思路。

l 注释表述应准 确、简单、明了。避免使用非常用缩写。

l 注释应避免语 言描述上存在二义性。

l 能够自解释的 命名、处理一般不再做注释，如变量“err_code”。

l 注释一般置于 需要说明的代码块的上方，空行以便与其它代码块隔开；或着，置于代码行的右侧。

不正确：

--获取窗口的宽度信息

v_win_main_width := get_window_property(p_window_main,width);

--主窗口宽度

v_win_popup_width := get_window_property(p_window_popup,width);

--弹出窗口宽度

v_win_x:= v_win_main_width / 2 - v_win_popup_width / 2;

--弹出窗口左边距

--设置弹出窗口位置

set_window_property(p_window_popup, x_pos, v_win_x);

正确：

--获取窗口的宽度信息

v_win_main_width := get_window_property(p_window_main,width); --主窗口宽度

v_win_popup_width := get_window_property(p_window_popup,width);--弹出窗口宽度

v_win_x:= v_win_main_width / 2 - v_win_popup_width / 2; --弹出窗口左边距

--设置弹出窗口位置

set_window_property(p_window_popup, x_pos, v_win_x);

...

l 如非必要，不 在表达式中间注释。

l 建议注释者采 用母语注释

2. 包注释规则

l 遵守通用注释 规则。

l 注释项包括： 创建人、创建日期、功能及说明、修改记录列表。修改记录包括修改日期、修改者、修改内容简述。

l 包内的过程、 函数修改时，在包的历史记录中也做简单描述。

create or replace package pkg_pol_uw is

--创 建 人：

--创建时间：

--说 明：

--修改记录：

--序号 修改日期 姓名 修改内容

-- 3 04/10/2002

-- 2 02/28/2002

01/31/2002

3. 过 程、函数注释规则

l 遵守通用注释 规则。

l 注释项包括： 创建人、创建日期、功能及说明、参数与返回值、主要逻辑或思路、修改记录列表。

l 在包内的过 程、函数，若创建人与创建日期与包注释一致，则省略之。

--创 建 人:

--创建时间：

--功能说明：

--主要逻辑：

--修改记录：

--序号 修改日期 姓名 修改内容

-- 2

-- 1

create or replace procedure p_uw_confirm as(
p_policy_id in number, --投保单ID
err_code out number, --错误代码
err_desc out varchar2 --错误描述
) is…

4. 对象、类型注释规则

l 遵守通用注释 规则。

l 对成员变量的 注释置于右方。

create or replace type r_cs_region_co is record(

exam_grade region_code_tbl.exam_grade%TYPE,--考核级别

region_co NUMBER, --地区系 数

achieve_std NUMBER --标准举 绩

);

type a_cs_region_co is table of r_cs_region_co;

5. 常量、变量注释规则

l 全局变量应从 功能、取值范围、处理原则等做详细描述。

--薪资计算状态。0-薪资尚未计算;1-薪资已发放

--过程SET_SALARY_STATUS修 改薪资状态的值，其它函数引用

g_salary_status varchar2(1);

6. 代码块注释规则

l 遵守通用注释 规则。

l 代码与注释应 紧邻，中间无空行。

l 注释必须与实 际代码相一致，不允许修改了代码逻辑却未修改相应注释的现象存在。

l 注释保持与相应代码的缩排。

不正确：

--增加对603的判断

if v_pol_ben.Plan_Code='603' then

...

end if;

正确：

--增加对603的 判断

if v_pol_ben.Plan_Code='603' then

...

end if;

l 必要时，在代 码块之前做整体的逻辑描述说明。

l 必要时，对变 量、分支语句（如条件循环）做注释。

l 良好的代码注 释，可以作为详细设计文档的一部分。

7. 代 码修改注释规则

l 若源代码已投 产，当代码需要局部调整而做增删改时，则在相应位置适当注释。

l 当源代码修订 时，取消代码中的增删改注释，同时做整体的修订注释。

例1、

--add by XXX at 2005-12-01 for原因及说明

… --新增代码

--add end

例2、

/*--delete by XXX at 2005-12-01 for原因及说明

… --删除代码

--*/delete end

例3、

… --修改代码 --modify by XXX at 2005-12-01 for原因及说 明

例4、

--… --原代码 --modify by XXX at 2005-12-01 for原因及说明

… --新代码