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
-- 1 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修 改薪资状态的值,其它函数引用
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原因及说明
… --新代码
来自 “ ITPUB博客 ” ,链接:http://blog.itpub.net/3618/viewspace-1032898/,如需转载,请注明出处,否则将追究法律责任。
转载于:http://blog.itpub.net/3618/viewspace-1032898/