《PBPB编码规范》word版.doc

PB PB编码规范PB-PB编码规范2010-12-07 15：10*综述*编程对象的分类以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 1w_about关于本系统的版权信息2 w_system_error系统出错提示3 w_main系统主界面4 w_report_sheet报表输出7.数据窗口普通数据窗口的命名必须以dW(DataWindow缩写)开头，代码表下拉式子数据窗口必须以dddw(DropDownDataWindow缩写)开头，加下划线(_)，其后紧接与数据窗口意义相关联的英文字母(总长不得超过PowerBuilder的40个字符限制)，并且在Comments框内写出该数据窗口的作用(中文或英文)，如下所示。序号数据窗口名称Comments 1d_system_error显示系统错误，被w_System_Error窗口调用2 d_categories对产品分类，被w_Report_Sheet窗口调用3 d_detail_parts Parts of Products Described in Detail 4d_detail_function Products Function Described in Detail 5dddw_sex性别代码表8.菜单菜单的命名必须以m(Menu缩写)开头，加下划线(_)，其后紧接与菜单意义相关联的英文字母(总长不得超过PowerBuilder的40个字符限制)，并且在Comments框内写出该菜单的作用(中文或英文)，如下所示。序号菜单名称Comments 1m_main Front End Main Menu 2m_report Report Subsystem Menu 3m_main_pop主界面的弹出菜单9.函数函数的命名必须符合类型f_subsystemname_detailname或lf_detailname格式，其中gf表示是全局函数，subsystemname是子系统的英文缩写，detailname是与函数意义相关联的英文字母(总长不得超过PowerBuilder的40个字符限制)，对于全局函数应该在Comments框内简短写出该函数的作用(中文或英文)，如下所示。序号函数名称Comments 1gf_help_index帮助子系统索引全局函数2 lf_get_user_info获取用户信息局部函数3 gf_query_sortbyname查询子系统名排序全局函数10.用户对象用户对象的命名必须以uo(UserObject缩写)开头，加下划线(_)，其后紧接与用户对象意义相关联的英文字母(总长不得超过PowerBuilder的40个字符限制)，并且在Comments框内写出该用户对象的作用(中文或英文)，如下所示序号用户对象名称Comments 1uo_external_function Cross platform user object ancestor 2uo_report_structure User Object as astructure For report 11.控件控件的命名必须以控件名称缩写开头，加下划线(_)，其后紧接与控件作用相关联的英文字母(总长不得超过PowerBuilder的40个字符限制)，如下所示序号控件名称控件缩写控件命名范例1 CommandButton cb cb_ok 2PictureButton pb pb_thank_info 3CheckBox cbx cbx_age_show 4RadioButton rb rb_typical_setup 5StaticText st st_user_id 6Picture pp_user_photo 7GroupBox gb gb_detail_info 8Line ln ln_h_separator 9Oval oval oval_used_flag 10 Rectangle rr_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 condition1 Then statementblock End If For varname=start To End Step increment statement_block Next(2)把单行注释与当前script程序的缩进位置对齐：/This is acomment For condition1 If condition1 Then/This is acomment For condition2 If condition2 Then/This is acomment For action1 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 variables Do While Sqlca.Sqlcode=0 statementblock fetch Cursorname into variables Loop Close Cursorname光标命名规则：Cur+_+名称。(2)调用数据库存储过程的编程约定如下：declare Procedurename procedure For StoredProcedureName：Value1，：Value2.；execute Procedurename；fetch Procedurename into variables；close Procedurename；commit；存储过程命名规则：Pro+_+名称。有些系统存储过程(例如：sp_droplogin)不能当做一个事务提交，为了执行它，就必须先置事物对象的AutoCommit属性为True，当存储过程执行完毕后再将事务对象的AutoCommit属性置为False。(3)在每一个SQL语句之后必须判断SQL语句执行成功与否，成功则继续，不成功则做相应处理并给出一条提示信息。If Sqlca.SqlCode 0Then 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_selectedNext不使用下述方法：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，背景色原则上为白色。Grid风格数据窗口一般不出现线条。14.数据窗口控件数据窗口控件命名规则：dw+_+功能含义。数据窗口边框