pb编程规范

PB-PB 编码规范 *综述 *编程对象的分类 以 PowerBuilder 作为前台开发工具，进行软件开发的过程中，所涉及的编程对 象如下所示 序号 类别 1 源代码 2 可执行代码 3 资源文件（如 pbr，bmp，ico 文件） 4 配置文件（如 ini 文件） 5 其他 *编程对象的组织 使用 PowerBuilder 开发工具产生的对象，可以按照设计（正在编写和调试）和 运行（调试、编译结束，可以接受测试和运行）中的状态进行编程对象的组织 规划，重点是目录结构的划分，具体目录的相对关系如下所示 类别 目录 说明 源代码 SrcCode 可按子系统再划分子目录（如 pbl 等文件夹） 可执行代码 Program 或项目名称 可按子系统再划分子目录 图片文件 Images 或 pic 等 包含应用图标 ICO 文件、BMP/JPG/GIF 文件 配置文件 Ini 其他 Other *版本说明 a. 软件版本号标准为 A . B，其中 A 和 B 为 0 到 99 之间的数字。 b. 当 A 大于 1 并且 B 为奇数时，表示当前版本为处于开发、测试阶段的版本， 定义为“开发版”；当 B 为偶数时，表示当前版本为稳定的、可实际运行的版 本，定义为“稳定版”。 c. 当软件开始开发时，确定版本号为 0.1；随着软件开发的进度，版本号随着 每一次主要功能的完善而变化，最高达到 0.99。 d. 软件初步开发完成后，经过软件开发小组内部测试，初步能够完成软件需求 提出的业务规范和技术要求，软件基本能正常运行，此时，确定该软件版本号 为 1.0 Beta X ，这意味着软件可以投入实际应用测试，其中 X 代表测试的次 数。 e. 当软件的 1.0 Beta X 版本推出并经过用户实际应用或者试运行测试后，此 时，确定该软件版本号为 1.0 RC。这意味着软件可以投入实际应用运行。 f. 当软件的 1.0 RC 版本投入实际应用运行达到某一时限后，则认为该版本已 经稳定，可以完全正常地使用了，这时，确定软件的版本号为 1.0，这意味着 软件开发完成，可以投入实际应用和推广。 g. 当软件进行升级时，如果功能变化不大，则次版本号变化；如果软件功能发 生重大变化时，主版本号变化。 *对象命名规范 *命名约定 a.部件名称可以达到 40 个字符，组成方式为 A_B。 b.A 部分表示前缀，表示部件的类型。 c.紧跟着一条下划线“_”。 d.B 部分描述此部件的名称。可以根据情况具体决定 B 的构成。推荐将 B 部分 分解成两部分： 功能代码_功能描述。 e.在重要变量后面写注解表示此变量的用途。 比如，常用的几种对象命名是 窗口的命名：w_功能代码_功能描述。 数据窗口控件的命名：dw_功能代码_功能描述。 数据窗口对象的命名：d_功能代码_功能描述。 菜单命名：m_功能代码_功能描述。 用户对象：uo_功能代码_功能描述。 *具体命名规则 1. 函数的命名规则 函数名=函数适用范围代码 +f+_+函数功能描述，其中函数的 适用范围代码和意义如下： g 全局函数； w 窗口函数； m 菜单函数； u 用户对象函数。 例：检查 SQL 语句执行结果的全局用户函数命名如下：gf_checksql()。 2. 应用 应用的命名应使用与该应用的意义相关联的英文字母，例如，app_si 表示社会 保险应用系统。 3. PBL 库 PBL 库组织的好坏很重要，它会影响应用开发和维护的容易程度以及应用的性 能。Library 的组织应遵循以下原则： a. Library 的大小。PowerBuilder 对 Library 的大小没有限制，但最好使之小 于 1MB，Library 太大，PowerBuilder 要花更多的时间去打开和存储对象，这 会影响开发的效率。 b. Library 的数量。尽量用最少的 Library 数量。应在 Library 的数量和每个 Library 中对象数量之间找到平衡点，如果 Library 数量太多而每个 Library 中对象数量太少，搜索路径会太长，影响运行效率。 c. Library 的优化。要在 Library 画笔中经常对 Library 进行优化。随着时间 的推移，Library 会被分段，会使 Library 的存储变得不连续，影响运行效率。 d. Library 的分类组织。PBL 库可按子系统或功能组织，一般应用都包含公共 PBL 库。每个 PBL 库文件命名应该与该文件作用相关联，例如报表 PBL 库文件 命名为 report.pbl。每个 PBL 库文件应该包含详细注释，列出该 PBL 文件包含 哪些对象，对应哪个子系统，与其他 PBL（调用）关系等信息。 为了有效地进行团队开发，实现对 PB 源码的管理，要求基于对各方因素（如应 用代码的执行效率和所占存储空间）和维护上的全面考虑，对 PB 源码实行分类 的原则。PowerBuilder 的 Library 的分类原则有两种方式： （1）制定对象分类法 根据所制定的不同类的对象进行分类。 例：将所有的窗口放在一个 Library 中。 （2）功能模块分类法 根据系统的功能模块的不同，将属于不同类的制定对象放在一个 Library 中。 这是一种更为有效的方式。 4. 初始化配置文件 初始化配置文件的命名必须与应用的名称一致，扩展名为.ini，例如： si.ini。用户的可变环境信息都应该保存在该文件中，关键信息加密保存，并 且提供管理工具，而不是手工修改该文件。 5. 资源文件 资源文件的命名必须与应用的名称一致，扩展名为.pbr，例如：si.pbr。 6. 窗口 窗口的命名必须以 w（Window 的首字符）开头，加下划线（_），其后紧接与窗 口意义相关联的英文字母（总长不得超过 PowerBuilder 的 40 个字符限制）， 并且在注释（Comments） 框内写出该窗口的作用（中文或英文），如下所示。 序号 窗口名称 Comments 1 w_about 关于本系统的版权信息 2 w_system_error 系统出错提示 3 w_main 系统主界面 4 w_report_sheet 报表输出 7. 数据窗口 普通数据窗口的命名必须以 dW（DataWindow 缩写）开头，代码表下拉式子数据 窗口必须以 dddw（DropDownDataWindow 缩写）开头，加下划线（_），其后紧 接与数据窗口意义相关联的英文字母（总长不得超过 PowerBuilder 的 40 个字 符限制），并且在 Comments 框内写出该数据窗口的作用（中文或英文），如 下所示。 序号 数据窗口名称 Comments 1 d_system_error 显示系统错误，被 w_System_Error 窗口调用 2 d_categories 对产品分类，被 w_Report_Sheet 窗口调用 3 d_detail_parts Parts of Products Described in Detail 4 d_detail_function Products Function Described in Detail 5 dddw_sex 性别代码表 8. 菜单 菜单的命名必须以 m（Menu 缩写）开头，加下划线（_），其后紧接与菜单意 义相关联的英文字母（总长不得超过 PowerBuilder 的 40 个字符限制），并且 在 Comments 框内写出该菜单的作用（中文或英文），如下所示。 序号 菜单名称 Comments 1 m_main Front End Main Menu 2 m_report Report Subsystem Menu 3 m_main_pop 主界面的弹出菜单 9. 函数 函数的命名必须符合f_subsystemname_detailname 或 lf_detailname 格 式，其中 gf 表示是全局函数，subsystemname 是子系统的英文缩写， detailname 是与函数意义相关联的英文字母（总长不得超过 PowerBuilder 的 40 个字符限制），对于全局函数应该在 Comments 框内简短写出该函数的作用 （中文或英文），如下所示。 序号 函数名称 Comments 1 gf_help_index 帮助子系统索引全局函数 2 lf_get_user_info 获取用户信息局部函数 3 gf_query_sortbyname 查询子系统名排序全局函数 10. 用户对象 用户对象的命名必须以 uo（UserObject 缩写）开头，加下划线（_），其后紧 接与用户对象意义相关联的英文字母（总长不得超过 PowerBuilder 的 40 个字 符限制），并且在 Comments 框内写出该用户对象的作用（中文或英文），如下 所示 序号 用户对象名称 Comments 1 uo_external_function Cross platform user object ancestor 2 uo_report_structure User Object as a structure For report 11. 控件 控件的命名必须以控件名称缩写开头，加下划线（_），其后紧接与控件作用相 关联的英文字母（总长不得超过 PowerBuilder 的 40 个字符限制），如下所示 序号 控件名称 控件缩写 控件命名范例 1 CommandButton cb cb_ok 2 PictureButton pb pb_thank_info 3 CheckBox cbx cbx_age_show 4 RadioButton rb rb_typical_setup 5 StaticText st st_user_id 6 Picture p p_user_photo 7 GroupBox gb gb_detail_info 8 Line ln ln_h_separator 9 Oval oval oval_used_flag 10 Rectangle r r_photo_frame 11 RoundRectangle rr rr_companyflag 12 SingleLineEdit sle sle_user_name 13 MultiLineEdit mle mle_book_comments 14 RichTextEdit rte rte_student_answer 15 EditMask em em_telephone_no 16 HScrollBar hsb hsb_time_set 17 VScrollBar vsb vsb_money_set 18 DropDownListBox ddlb ddlb_your_favourite 19 DropDownPictureListBox ddplb ddplb_photo_preview 20 ListBox lb lb_department_name 21 PictureListBox plb plb_user_identification 22 ListView lv lv_all_user 23 TreeView tv tv_customers 24 TabPage tpg tpg_ordinary_super 25 Tab tab tab_super 26 DataWindow dw dw_user_info_detail 27 Graph gr gr_month_report 28 Ole ole ole_word_doc *变量命名规范 变量取名应遵守命名规范，对使用频繁的或关键变量，为了便于阅读和修改， 在定义时应加上注释标明其含义。例如： String ls_name / 参保人员姓名 变量命名规则为： 变量范围 + 变量数据类型 + _ + 含义代码 *变量数据类型约定 数据类型 前缀 Any a_ Blob bb_ Boolean b_ Character c_ Date d_ DateTime dt_ Decimal dec_ Double db_ Integer i_ Long l_ String s_ Time t_ UnsignedInteger ui_ UnsignedLong ul_ DataWindow dw_ DataWindowChild dwc_ MailSession ms_ Menu m_ Structure str_ Transacttion trans_ Window w_ UserObject uo_ *变量范围命名约定 范围 字首 描述 Global g?_ 全局变量将在整个应用中有效。它们可能从 其他对象面板中定义，但它们将在整个应用中有效 Shared s?_ 共享变量在一个对象及其实例中有效 Instance i?_ 实例变量仅在一个对象的实例中有效。相应对象 的不同实例中的变量保存各自的值 Local l?_ 局部变量仅在一段子程序或在 script 开始和结束时生效 由值传递的变量 v?_ 在定义函数时，参数仅传递值，不会被函数 (仅适用于函数变量) 改变，定义为 value,例：vdw_datawindow 由引用传递的变量 r?_ 在定义函数时，参数将被此函数改变， (仅适用于函数变量) 定义为 reference， 例：rl_long 注意：？表示相应数据类型，如 i,c,l,s 等数据类型前缀。 对于上述的内容做如下说明。 a. 全局变量的命名必须符合 gT_subsystemname_detailname 格式，其中 g 表示 是全局变量（Globe），T 是数据类型（DataType）的简写。subsystename 是子 系统的英文简写。detailname 是有具体意义的英文字母。例如： gs_query_user_info ，即为查询子系统定义了一个字符串型全局变量。 b. 局部变量的命名必须符合 lT_detailname 格式，其中 l 表示是局部变量 （Local），T 是数据类型（DataType）的简写。例如：li_user_salary ，即 定义了一个整数型局部变量。 c. 实例变量的命名必须符合 iT_detailname 格式，其中 i 表示是实例变量 （Instance），T 是数据类型（DataType）的简写。Detailname 是有具体意义 的英文字母。例如：is_product_name ，即定义了一个字符串型实例变量。 *编程规范 *书写格式 a.用分层缩进的写法显示嵌套结构的层次。 b.在注释段与程序段，以及不同逻辑的程序段之间插入空行。 c.每行只写一条语句，当需要滚动显示时应该分行书写。 *流控制 流控制首先应遵守 PowerBuilder 语法规范，且用分层缩进的写法突出显示嵌套 的层次结构，例如： For i = 1 To 100 For j = 1 To 50 For k = 1 To 200 Matrixi，j，k=1 Next Next Next *注释及格式要求 注释总是加在程序中需要概括性说明或不易令人理解或容易令人理解错的地方。 注释语言应简练、易懂而又准确，所采用的语种首选是中文，如有输入困难或 特殊需求也可采用英文。 注释原则： a.函数或过程的注释 (1)在函数头部必须说明函数的功能和参数（值参、变参）； (2)在函数的主体部分，如算法复杂时，应以注释的方式对其算法结构做出说明； (3)函数申请过全局资源且有可能导致资 源紧张应加以注明(如内存和文件柄等)； (4)函数有副作用一定以十分醒目的方式(如加!号等)注明。 b.语句的注释 (1)应对不易理解的分支条件表达式加注释； (2)不易理解的循环，应说明出口条件(有 GOTO 的程序还应说明入口条件)； (3)过长的函数实现，应将其语句按实现的功能分段加以概括性说明。 c.常量和变量的注释 在常量名声明后应对该名做适当的注释，注释说明的要点是： (1)被保存值的含义(必须) ； (2)合法取值的范围(可选)； (3)全局量需要对以上逐点做充分的说明。 d.制定对象的注释 每个开发人员针对自己所制定的窗口、菜单、数据窗口、数据管道和用户对象 等添加注释，要点是： (1)标注对象的用途； (2)标注对象的制定人员； (3)标注时间或者修改时间。 具体格式要求如下： 1. 在窗口 Open 事件前应说明 /* = */ / 窗口中英文名称： / 窗口作用： / 作者： / 日期： /* = */ 2. 在事件脚本(Script)之前应说明 /* = */ / 脚本作用： / 输入参数及数据类型： / 返回参数及数据类型： / 全局函数及其用途： / 全局变量及其用途： / 作者： / 日期： / 修改人的姓名： / 修改日期： / 修改原因： /* = */ 若有多人修改，每个人均加上自己的注释，而不能改他人的姓名、日期、原因， 对要修改的脚本，只能注释不能删除，并且在修改的地方加上修改人名、日期 和“Beginning Modification. “，“Ending Modification“字样。 3. 脚本中的注释 单行脚本程序注释： / 注释文本 脚本的程序段注释： /* = */ / / 注释文本 / /* = */ 变量的注释如下： 数据类型 变量名 /注释 4. 在函数、存储过程等脚本(Script)之前应说明 /* = */ / 函数名称： / 参数解释： / 功能描述： / 调用举例： / 最初作者： / 编写日期： / 返 回 值： / 变量情况： / 修 改 人： / 修改日期： / 修改原因： /* = */ *Powerbuilder 脚本编程规范 1. Powerbuilder 编程注意事项 a.不要在子应用中声明全局变量！如必须声明全局变量，则应事先向项目负责 人申请。 b.供别的文件或函数调用的函数，绝不应使用全局变量交换数据。 c.所有 SQL 语句均需判断返回结果(包括 SELECT，COMMIT 语句)。 例： If sqlca.sqlcode = -1 Then 错误处理程序 跳出 Else 正常 End If d.缺省 SQLCA 的连接语句 connect，在应用 Open 事件中完成，其 disconnect 在主应用的 Close 事件中完成，其余任何 pbl 中均不能有 disconnect 语句。 e. 由于要连接多个数据库，需要用 Create 创建对象，比如：SQLSYB，则用 connect using SQLSYB，处理完毕后用 disconnect using SQLSYB，并且用 destroy SQLSYB 释放资源。 2. 编码标准 （1）在代码块前后留一个空行。例子如下： If Then End If For = To Step Next （2）把单行注释与当前 script 程序的缩进位置对齐： /This is a comment For condition1 If Then /This is a comment For condition2 If Then /This is a comment For action1 End If End If （3）缩进应以 Tab 键实现，不得采用空格。 （4）变量采用小写格式。注意： 变量全部用小写； 一个变量一行，每个变量必须注释； 通常情况下，变量的后半部分尽量用数据库字段名； 变量声明全部在脚本之前声明完毕； 所有变量声明时按代码功能段 + 变量类型进行排序。例如： Long ll_quantity String ls_name 对象名采用小写，属性、关键字、保留字和内置函数均用首字母大写格式： w_cont_de.Visible = True m_mdi.m_file.m_print.Enabled = False 数据窗口控制的函数加上修饰，而不以数据窗口对象作为参数： dw_main.SetTransObject(sqlca) dw_main.SetRowFocusIndicator(Hand!) dw_main.Retrieve() （5）当连接起来的字符串超过了两行的长度时，使用 + 符作为下行的第一个 字符，每次均采用缩进格式。字符串的随后部分应该再次缩进。例如： ls_msg = “连接数据库失败！错误信息为：rn“ & + Sqlca.SqlErrText & + “请与系统管理员联系“ （6）PowerBuilder 保留字(关键字)首字母大写其余小写，这样看起来层次清 晰，如：This，Parent，ParentWindow，True，False，Return，Halt 与 Close。 （7）PowerBuilder 内部函数及属性每个字首字母大写其余小写，这样看起来 层次清晰，如：sle_user.Text，dw_1.SetTransObject(Sqlca)， Sqlca.SqlErrText。 （8）SQL 语句按如下格式书写： SELECT name，sex，dept_id INTO ：ls_name，：ls_sex，：ls_dept_id FROM employee WHERE emp_id = ：ls_emp_id ； （9）程序中应避免出现 goto 跳转语句。 3. 脚本中一些常用功能模块的编程约定 （1）光标操作过程的编程约定如下： Declare Cursorname Cursor for Select 语句 Open Cursorname； fetch Cursorname into Do While Sqlca.Sqlcode = 0 fetch Cursorname into Loop Close Cursorname 光标命名规则：“Cur” + “_” + 名称。 （2）调用数据库存储过程的编程约定如下： declare Procedurename procedure For StoredProcedureName ：Value1，：Value2； execute Procedurename； fetch Procedurename into ； close Procedurename； commit； 存储过程命名规则：“Pro” + “_” + 名称。 有些系统存储过程（例如：sp_droplogin）不能当做一个事务提交，为了执行 它，就必须先置事物对象的 AutoCommit 属性为 True，当存储过程执行完毕后 再将事务对象的 AutoCommit 属性置为 False。 （3）在每一个 SQL 语句之后必须判断 SQL 语句执行成功与否，成功则继续，不 成功则做相应处理并给出一条提示信息。 If Sqlca.SqlCode 0 Then Rollback ； MessageBox(“错误信息“，“操作失败！“) Else Commit； MessageBox(“提示信息“，“操作成功！“) End If （4）所有操作符（包括等号）前后应留一空格，使程序看起来更清晰。例如： ls_msg = ls_title + ls_error （5）仅当绝对需要时才在循环结构体中使用函数调用，也就是说，仅当函数的 返回值依赖于循环迭代的值时才使用函数调用。 使用如下方法: Long ll_num_selected ll_num_selected = lb_devctg.TotalSelected() For i = 1 To num_selected Next 不使用下述方法： For i = 1 To lb_1.TotalSelected() Next 4. PB 中的任何一个窗口都要有注释说明 一般在窗口的 Open 事件中对窗口的功能进行全面的介绍，以便维护人员可以很 清楚地知道窗口的功能和维护要点。其格式可参见前面的说明。 5. 表的操作 在程序中涉及多个表的操作时，需严格按照各项目组“表操作顺序一览表”规 定的顺序对表进行操作，以防发生锁表现象。 *控件编程规范 *公共部分 a.应尽量为所有控件使用有意义的名称，重要控件不允许使用 pb_1 之类无明 确意义的名称。 b.大号字体：各窗口控件字体为 Arial，字号为 12 号，字色为黑色。小号字体： 各窗口控件字体为宋体，字号为 9 号，字色为黑色。 c.显示控件和输入控件底色分开，显示控件为灰色(窗口颜色)，输入控件为白 色。 d.输入区和显示区分别放置。 e.按钮排列紧凑，在窗口右侧纵向排列时靠上放置；在窗口下方排列时靠右放 置，因为左撇子操作者毕竟是少数。 f.各字符类控件对齐方式为左对齐；数字类控件为右对齐，且必须按所需格式 设置 Format 属性；日期控件必须保证能完整显示所需日期格式，应用 yyyy- mm-dd 风格。及有前导 0 的形式（避免 2000 年问题），可采用左对齐或中对齐。 g.CommandButton 控件的推荐高度为 104。 *控件细则 1. 静态文本框 静态文本框命名规则：st + _ + 名称（若为 label 可不改名）。 外观规定如下： 背景色：buttonface； 前景色：黑色； 边 框：无； 高 度：72。 建议在其后加上全角冒号（：）。 2. 单行编辑框 单行编辑框命名规则：sle + _ + 名称。 （1）外观 背景色：白色； 前景色：黑色； 边 框：3D Lowered； 高 度：72。 （2）程序说明 a.响应事件建议自定义 Keydown 事件，尽量不要用 Modify 事件。 b.当获得焦点时控件背景变为深蓝色，字体颜色变为黄色，失去焦点时还原缺 省颜色。 3. 命令按钮 命令按钮命名规则：cb + _ + 名称 （1）外观 高度：对于小号字体（宋体 9 号）为 92； 对于大号字体（Arial 12 号）为 108。 宽度：对于小号字体（宋体 9 号）为 325； 对于大号字体（Arial 12 号）为 402。 （2）说明 命令按钮控件不要使用 cb_1 之类无明确意义的名称(尤其在窗口中这类控件比 较多时，可能令人分不清各个控件的作用)。 4. 图像按钮 尽量不用图形按钮，而用命令按钮。 图像按钮命名规则： pb + _ + 名称。 外观规定如下： 尺寸：用图像原始尺寸； 图像：按钮的有效与无效采用不同的 bmp 图像以示区别。 5. 复选框 复选框命名规则：cbx + _ + 名称 外观规定如下： 背景色：buttonface； 前景色：黑色； 边 框：3D Lowered； 高 度：92； 位 置：标签在右。 6. 单选按钮 单选按钮命名规则：rb + _ + 名称。 （1）外观 背景色：buttonface； 前景色：黑色； 边 框：3D Lowered； 高 度：92； 位 置：标签在右。 （2）程序说明 单选按钮最好与组框配合使用。 7. 组框 组框命名规则：gb + _ + 名称。 外观规定如下： 背景色：buttonface； 前景色：黑色； 边 框：3D Lowered。 8. 屏蔽编辑框 屏蔽编辑框命名规则：em + _ + 名称。 （1）外观 背景色：白色； 前景色：黑色； 边 框：3D Lowered。 （2）程序说明 a.响应事件建议用自定义 Keydown 事件，尽量不要用 Modify 事件。 b.当获得焦点时控件背景变为深蓝色，字体颜色变为黄色，失去焦点时还原缺 省颜色。 9. 下拉列表框 下拉列表框命名规则：ddlb + _ + 名称。 外观规定如下： 背景色：白色； 前景色：黑色； 边 框：3D Lowered。 10. 应用 应用命名规则：app + _ + 应用名。 为应用选择一个图标，以便在运行时标识应用。 在 Open 事件中声明 SQLCA 全局变量和打开应用主窗口。 在 Closequery 事件中编写退出应用之前的处理程序。 在 SystemError 事件中编写系统出错的处理程序。 11. 窗口 窗口命名规则： w + _ + 窗口名。 主窗口采用 main 窗口类型，子窗口一般采用 Popup 窗口类型，无控制菜单， 无最大化最小化按钮，不可改变大小。若为一般性提示窗口，用 response 窗 口类型。 窗口以 buttonface 颜色为背景颜色。 重要的菜单选项设置 Toolbar 功能。 窗口上下左右四周应至少留出两个网格，而不得将对象填满整个窗口！ 12. 菜单 菜单命名规则： m + _ + 菜单名。 菜单项 MenuItem 的名称以该菜单项在整个菜单中的物理位置分层次命名。 例：若 MenuItem 位于整个菜单的第三列第二行，则命名为 m_32。 或文件菜单下的“关闭”菜单项，则命名为 m_file_close。 13. 数据窗口对象 数据窗口对象命名规则：d + _ + 功能含义。 打印用数据窗口背景色为白色，题目为 16 号字，内容为 11 号字，显示比例为 75%。 显示用数据窗口背景色原则上为 buttonface，可视窗口制作是否美观的实际情 况使用白色数据窗口各列显示框高度为 72。 Tabular 和 Grid 风格数据窗口，无表头时列名文本边框为 3D Raised。Detail 区为 3D Lowered，背景色原