PB编程规范(v4.0).doc

厦门智业软件工程有限公司.研发部ZHIS4项目组文档密级公开（）普通（）秘密（）机密（）绝密（）PB编程规范文档编号：文档归类：项目规范文档作 者：李程扬创建时间：2002-07-02修改时间：2005-09-29版 本 号：v3.0(2002-07-31)、v4.0(2005-09-29)文档传阅：ZHIS4项目组成员为提高程序开发效率，降低软件开发过程中出现错误的几率，使系统模块保持一致的风格，在开发过程中应该遵循一定的编程标准。规范提供的是定义一个源码级应用程序的开发规范，它是借助PowerScript语言，在PowerBuilder开发环境下提供的标准化服务。它可供应开发人员及系统设计人员使用。本规范描述开发人员关心的外部特性及设施，而不是描述为达到这些功能采用的内部结构技术。1、 命名规范:1.1 命名总则：1.1.1 除了特殊说明外，所有命名均须使用规定的前缀标识，即“标识_功能说明”；1.1.2 所有命名的功能说明部分均为用下划线(_)分隔单词；1.1.3 “功能说明”部分的单词先后顺序以尽量使同一类别的对象排列在一起为原则，以便于查找定位；1.1.4 绝对禁止用单纯的数字或汉语拼音简码来命名，如ls_1、ls_brxm（病人姓名），必须使用与具体功能相关的单词或单词缩写，且尽可能使用行业常用术语或约定词汇，即词能达意、沟通方便；1.1.5 命名的原则是尽量能从名称上看出更多的隐含基本信息，如变量的作用域、变量类型等；1.2 对象命名规范:对象名称命名规则示例备注1应用对象subsystem_namedoctor2工程对象p_subsystem_namep_doctor3窗口对象w_namew_sheet_manager主窗口(w_main)4普通菜单对象m_namem_report主菜单(m_main)5弹出式菜单m_pop_namem_pop_register6普通数据窗口d_named_sick_info7外部数据窗口d_ext_named_ext_dept_select外部数据源External8下拉子数据窗口dwc_namedwc_base_dict9标准可视用户对象u_nameu_cb_help 注10可视用户对象uo_nameuo_login继承自Custom Visual11不可视用户对象n_namen_pres_save12全局函数f_namef_get_sys_parm13全局结构st_namest_print注：继承普通按钮commandbutton(u_cb_)、继承数据窗口datawindow(u_dw_)注意事项A.对象命名:对象类型标识_功能说明，当然应用对象命名无须前缀标识；A.对于窗口与数据窗口的命名，推荐采用“标识_子类别_名词_动词_备注”命名方式，这样可以把同类对象排在一起，编程时便于查找，应用框架也较为明晰； 例如：w_employee_edit_grid w_employee_edit_free d_dept_preview d_dept_config d_query_apply_sheet d_query_lay_physic d_rpt_staff_print_free d_rpt_staff_print_grid 由上，对于数据窗口子类别命名可遵循：打印(print)、查询(query)、报表(rpt)A.对于有继承关系对象的命名（窗口、菜单、用户对象），推荐用“父类_子类说明”； 例如：w_spell w_spell_apply w_spell_apply_sick u_dwbutton u_dwbutton_add1.3 变量命名规范:1.3.1 变量作用域前缀:变量范围缩写示例说明1全局变量(Global)GGS_SUBSYSTEM_NAME2共享变量(Shared)SSL_ITEM_COUNT3实例变量(Instance)IIS_TEMPLATE_FLAG4局部变量(Local)lls_prescribe_number5传值参数变量(Value/ReadOnly)aas_apply_no6引用参数变量(Reference)rrdc_sum_cost注意事项A.编程时对于全局变量、共享变量与实例变量能不使用时尽量不用，如可以用参数传值时就不要定义实例变量；1.3.2 变量类型前缀:变量类型缩写示例说明1字符串(String)sls_item_code2日期(Date)dld_register_date3时间(Time)tlt_dose_time4日期时间(DateTime)dtldt_sys5短整型(Integer、Int)ili_count6长整型(Long)lll_handle7数值类型(Decimal、Dec)dcldc_lay_quantity8布尔类型(Boolean)blb_physic_flag9二进制对象(Blob)bloblblob_test_pic10Any类型(Any)anylany_data11数据存储(DataStore)dslds_physic_storage12数据窗口(DataWindow)dwldw_cost13子数据窗口(DataWindowChild)dwcldwc_dept14PowerObject对象(PowerObject)polpo_parent15DragObject对象(DragObject)doldo_set16应用对象(Application)applapp_doctor17OLE对象(OLEObject)olelole_word18TreeViewItem对象(TreeViewItem)tviltvi_class19异常处理对象(Exception)ele_sql20按键(KeyCode)kGK_HOT_KEY21不可视用户对象(Custom Class)nvlnv_check22可视用户对象(Custom Visual)uoluo_report注意事项A.字符串类型统一用String，而不准使用Char类型；A.日期类型推荐以“_date”作为后缀，时间类型以“_time”作后缀，A.整型定义推荐都使用Long，因为Integer短整型最大值为32767，某些情况下可能会溢出；另外无符号长整型（UnsignedLong）与短整型（UnsignedInteger）的前缀与有符号类型一样；A.浮点类型统一使用Decimal，不用Double或Real类型；Decimal在定义变量时须指定精度，即使是无小数位的情况下；若是存数据库列值的变量一定要注意与列的小数精度一致，这一点切记；例如：Dec3 ldc_pres_cost Dec0 ldc_nullah_number Dec2 ldc_lay_physic_quantity Dec2 ldc_physic_pack_specA.对于存数据库数值类型列的变量一定要注意其是否有小数及其位数，另外，一定要使用Decimal类型变量，绝对不准使用Long类型，即使当前值它位数足够，但你不能保证将来变动时Long类型变量位数也足够存其值！A.对于其它没列出的对象类型，取其单词首字母为前缀；例如：TranceObject lto_connect1.3.3 变量访问范围:注意事项A.所有共享变量或实例变量都必须设置访问范围（Public、Protected、Private），不推荐使用Public类型，而用of_get_xxx与/或of_set_xxx向外提供封装接口；A.在对象内使用全局变量时，尽可能在使用前把它赋值给同类型的实例变量，以使模块移植性更好（方便），例如，对象Constructor事件或窗口Open事件中： IS_LOGIN_DEPT_CODE = GS_LOGIN_DEPT_CODE1.3.4 变量名称:注意事项A.对于从数据库或数据窗口中取值的变量，其后部分尽量用数据库字段名； 例如：String ls_item_name Dec3 ldc_total_dosage 1.4 控件命名规范:控件名称缩写示例说明1CommandButtoncb_cb_ok2PictureButtonpb_pb_thank_info3CheckBoxcbx_cbx_age_show4RadioButtonrb_rb_typical_setup5StaticTextst_st_user_id6StaticHyperLinkshl_shl_service_email7Picturep_p_user_photo8PictureHyperLinkphl_phl_company_sign9GroupBoxgb_gb_detail_info10Lineln_ln_h_separator11Ovalov_ov_used_flag12Rectangler_r_photo_frame13RoundRectanglerr_rr_company_flag14SingleLineEditsle_sle_user_name15EditMaskem_em_telephone_no16MultiLineEditmle_mle_book_comments17RichTextEditrte_rte_student_answer18HScrollBarhsb_hsb_time_set19VScrollBarvsbvsb_money_set20HTrackBarhtb_htb_people_set21VTrackBarvtb_vtb_quantity_set22HProgressBarhpb_hpb_work_info23VProgressBarvpb_vpb_cost_info24DropDownListBoxddlb_ddlb_your_favourite25DropDownPictureListBoxddplb_ddplb_photo_preview26ListBoxlb_lb_department_name27PictureListBoxplb_plb_user_identification28ListViewlv_lv_all_user29TreeViewtv_tv_customers30DataWindowdw_dw_user_info_detail31Graphgr_gr_month_report32OleControlole_ole_word_doc33UserObjectuo_uo_sick_info34Tab Controltab_tab_pres_query35TabPagetabpage_tabpage_ordinary_super注意事项A.控件命名:“控件类型前缀_功能说明”,界面设计时其作用范围不用标示，如树形控件tv_physic；但在脚本中定义时必须遵循变量命名规范，如数据窗口控件：idw_send；A.界面设计时不能使用控件的缺省名称（如cb_1,dw_2），须用与控件功能相关的单词，单词间用下划线(_)相隔；当然一些图示控件（如GroupBox,Line）可以除外；一般界面有多个相同类型控件或控件名要在代码中引用时就要改变其缺省定义。1.5 常量命名规范：注意事项A.因为到PB8还不支持枚举类型，对于一些有固定取值范围的变量值可用常量定义，这样程序员在使用时可见其词知其义，特别是对于一些状态值推荐使用常量，这样可读性更好，例如：Public: Constant String APPLY_STATUS_NEW = NEW /单据新开态 Constant String APPLY_STATUS_EXEC = EXEC /单据执行态A.常量命名无须有前缀或后缀，一般取大家均知其含义的单词组合，如数据库状态列就取“列名+状态名”，同样其单词间也用“_”分隔；1.6 内部函数命名规范:函数类型缩写示例说明1私有函数(Private)、pf_pf_insert_apply2保护函数(Protected)vf_vf_retrieve3公有函数(Public)of_of_get_sick_id注意事项A.函数命名单词间以“_”相隔，公用函数命名应采用“of_get_xxx”、“of_set_xxx”、“of_is_xxx”、“of_found_xxx”等类似的形式；A.命名能使相同功能的函数尽量排列在一起，以便于查找，可采用“功能描述+动词+名词”，例如： of_dw_set_row() /数据窗设置当前行状态 of_dw_retrieve() /数据窗刷新 of_dw_save() /数据窗保存 of_dw_save_check() /数据窗保存时检查数据有效性A.有以下情况可能会因前缀相同而易产生混淆，当可视用户对象及其窗体容器的函数名相同，而此时又在用户对象的事件中调用此函数，如of_set_status，就不易区分到底是调用对象的函数()还是调用窗体的函数，因此特规定：在用户对象的事件中调用函数时必须加上“This.”,如：This.of_set_status()1.7 事件命名规范:注意事项A.对象事件以“ue_”作前缀，单词间用“_”相隔，如：ue_open_after /Open事件之后触发ue_retrieve_tv /刷新树形控件A.同样命名的原则也是尽量使同一类的事件放在一起，只要不引起误解，对于“动词”与“名词”哪个排前并无太大关系，以便于查找定位某一事件及相关事件为原则；A.自定义事件一般用于两种场合：a.封装控件处理； b.动态界面消息传递。1.8 结构命名规范：注意事项A.不论全局结构还是对象内部结构均使用“st_”作前缀，命名时单词间也用“_”分隔；但“全局结构对象”不推荐使用，因其自身无法包含足够的注释，这样会造成理解不便，所以，除了要与已开发系统兼容外不准使用结构对象，而用不可视对象代替，如下A.对于要使用全局结构对象的场合，可用不可视对象来代替，并以“_var”作后缀以示与普通不可视对象相别，如：n_tv_dept_varPublic: /n_tv_dept_var的实例变量定义 String DEPT_CODE /科室代码 String DEPT_NAME /科室名称在使用定义时同结构对象，如：n_tv_dept_var lst_deptlst_dept.dept_code = ls_dept_codeA.结构对象内部变量（属性）的命名无须用任何前后缀，如st_clinic.item_codeA.结构对象一般用于参数传递1.9 SQL语法对象命名:数据库对象类型缩写示例说明1数据库游标(Cursor)cur_cur_pres_price2数据库存储过程(Stored Procedure)sp_sp_set_pres_status3数据库后台函数(Fuction)f_f_get_residence_no注意事项A.在PB脚本中定义时其作用范围不用标示；A.数据库的存储过程与函数类型的具体书写格式详见3.2.8与3.2.0；1.10 PBL库命名规范:PBL库存放对象后缀示例备注1应用对象、工程对象、菜单对象、结构对象cost.pbl2不可视用户对象Custom UserObject_ncost_n.pbl3可视用户对象Visual UserObject_uocost_uo.pbl4普通数据窗口（含外部数据源）DataWindow_dcost_d.pbl5子数据窗口DataWindowChild_dwccost_dwc.pbl6全局函数Fuction_funcost_fun.pbl7窗口对象Window_wincost_win.pbl8所有作废对象缓存，类似垃圾箱，不包含入应用_zcost_z.pbl注意事项A.不可视用户对象较少时可归入cost_uo.pbl中；子数据窗口较少时亦可归入cost_d.pbl中；其它的同理可都归入cost.pbl之中，可以0.5M为库文件合并的下限；A.pbl库文件以2M为上限，若大于此就要考虑拆分库文件，可用相似功能分类，如：cost_dw.pbl(其它数据窗)、cost_dw_stat.pbl(统计数据窗)；当然，若难以分类可用数字区分，如cost_dw.pbl、cost_dw1.pbl、cost_dw2.pbl等等；A.cost_z.pbl是个较特殊的库，它不用包含在应用pbt文件中，里面可放一些已删除的库对象，为了防止误删，养成好的习惯把这些对象移到这个专门的垃圾对象存放库是有好处的；A.以上pbl库命名规范，还有按对象类别归划的方法是针对在本子系统内部使用对象，至于那些要与其它子系统公用的对象，应把它们按功能归到一个单独的pbl库中，以利于其它子系统及时同步更新，这类pbl库命名要突出其功能，如login.pbl(登录模块)，当然还可以加上子系统名称作前缀，如nurse_pres.pbl（住院医嘱管理），pbl库名称单词间同样要以“_”作分隔；A.另外有一点须要特别注意，以下几类对象在不同pbl库中有重名时编译时是不会报错的：不可视用户对象、全局函数、数据窗口对象，重名主要应是与公用库，这要此起足够重视，包含新的公用库时要检查是否有与应用库冲突；1.11 其它文件命名规范:1.11.1 初始化配置文件：其命名与应用的名称一致，扩展名为.ini，如：nurse.ini1.11.2 编译用资源文件：其命名与应用的名称一致，扩展名为.pbr，如：nurse.pbr1.11.3 应用目标集文件：其命名与应用的名称一致，扩展名为.pbt，如：nurse.pbt1.11.4 应用工作区文件：其命名与应用的名称一致，扩展名为.pbw，如：nurse.pbw，一般都用统一的工作区文件zhis4.pbw1.11.5 至于这些文件的放置目录及目录规范请参见项目开发环境配置说明；2、 大小写规范:2.1 大小写总则：单词间有下划线(_)分隔书写时全部小写，否则用首字母大写。2.1.1 PB内部名称:均用首字母大写其余小写格式，使代码层次清晰：2.1.1.1 PB保留字(关键字)：This，Super，Parent，ParentWindow，True， False，Return，Close，Halt，String，Decimal，Select，Update 2.1.1.2 PB内置函数：dw_detail.SetTransObject(Sqlca)，SetFocus()2.1.1.3 PB内置枚举变量：DataModified!，Question!，KeySpaceBar!2.1.1.4 对象的属性：cb_save.Enabled = False，sle_user.Text = ls_user2.1.1.5 数据库函数：Decode，SubStr/Oracle PL/SQL函数2.1.1.6 其它未列出的属PB已定义命名的全部为单词首字母大写2.1.2 程序员定义名称：全部小写；2.1.2.1 局部变量：ls_physic_spec,ldw_master2.1.2.2 控件名称：tv_return，cbx_show_msg，uo_dosage_date2.1.2.3 函数及事件：f_menu_set,of_lay_cost,ue_reset_tree2.1.2.4 数据窗列名：ic_card_id，dept_code2.1.2.5 系统参数名： ls_pool_day = f_get_sys_parm(lay_pool_day)2.1.2.6 数据库对象名、字段名等：base_dict（表），apply_no（字段）2.1.2.7 其它未列出的程序员可自己命名的名称全部小写；2.1.3 其它特例：2.1.3.1 全局变量、共享变量、实例变量全部大写，对象定义除外，例如idw_copy2.1.3.2 本地参数名全部大写ll_browse_day = f_get_ini(REGISTER_BROWSE_DAY)注意事项A.大小写规范仅是推存大家使用，并不要求一定要照上所述，若不按上述大小写风格，可采用本人较为熟悉的风格，如全部都小写，但整个子系统一定都要保持同一种风格，这是最基本的原则；3、 脚本书写格式:3.1 书写格式细则：3.1.1 脚本书写以整洁美观为原则，注意代码的可读性第一、效率才是第二；3.1.2 脚本不要写得太长，若超过200行，就应考虑拆分为多个子函数；3.1.3 在条件语句中应多使用括号以避免二义性；If ( Not Isnull(ls_status) ) And ll_row 0 ThenEnd if3.1.4 用分层缩进（缩排）的写法以显示嵌套结构的层次，缩排应以“Tab键”来实现，绝对不能采用空格！缩进循环及其它复合语句中的代码，这样可以清楚显示代码间的包含关系，另外，要把单行注释与当前脚本程序的缩进位但对齐；/注释If ll_row 0 Then /注释 For i = 1 to ll_count /注释 NextEnd IF3.1.5 变量定义在程序段的开头，即尽量在用的地方才定义，但又不可太过分散，相同类型变量放在一起，即按“代码功能段+变量类型”进行排序，且使用“Tab键”分隔变量类型和变量名，以保证上下两行的排列整齐；（非强制要求）Longll_rowStringls_physic_codeStringls_physic_name3.1.6 在大段注释与程序段，以及不同逻辑的程序段之间插入空行；3.1.7 下列地方必须使用空格，以使程序看起来更清晰；（非强制要求）3.1.7.1 所有操作运算符前后ls_msg = ls_title + ls_error3.1.7.2 函数参数之间of_get_sick_name(ls_sick_id, ls_sick_name)3.1.7.3 同一行声明的变量之间Integer i, j ,k3.1.8 当需要滚动显示时就应该分行书写，在续行时应把连接标记（如And,+）放在行的末尾，续行处与前一行对齐；ls_sql = Where apply_no = + ls_apply_no + + & And apply_sub_no = + ls_apply_sub_no + 3.1.9 单行结构的语句推荐分解为多行，即每行只写一条语句如（非强制要求）If ll_row 0 Then dw_report.Retrieve()应用如下写法，以示清晰If ll_row 0 Then dw_report.Retrieve()End if3.1.10 程序中应尽量避免出现“Goto”跳转语句；3.1.11 SQL语句其关键字推荐应靠右对齐，参见3.33.2 常见PB控制语句格式约定：3.2.1 If条件判断格式如下：If ll_count = 1 Then /条件处理Else /注:当ll_count为空时，处理会转向ElseEnd If3.2.2 Choose条件判断格式如下：Choose Case ll_percentCase Is 80Case 70 To 80Case 60Case ElseEnd Choose3.2.3 For循环语句格式如下：/仅当函数的返回值依赖于循环迭代的值(i)时才可在结构体中使用函数调用ll_count = dw_query.RowCount()For i = 1 To ll_count Step 1 /循环体Next3.2.4 Do循环语句格式如下：DoLoop While True或Do While TrueLoop3.3 常用SQL功能模块格式约定: 3.3.1 Select语句格式如下:Select name,sex,rate_type, Into :ls_name,:ls_sex,:ls_rate_type From sick_basic_info Where sick_id = :ls_sick_idFor Update;If f_SqlErr()0 Then Return 1If Sqlca.SqlCode = 100 Then 3.3.2 Update语句格式如下:Update dispensary_sick_cure_info Set doctor = :ls_doctor , register_status = :ls_register_status Where nullah_number = :ldc_nullah_number;If f_SqlErr ()0 Then Return 1If Sqlca.SqlnRows1 Then /出错提示3.3.3 Insert语句格式如下:Insert Into apply_sheet_detail_pool (apply_no, item_sequence, item_code, item_name )Values(:ls_apply_no, :ldc_item_sequence, :ls_item_code, :ls_item_name );If f_SqlErr ()0 Then Return 1If Sqlca.SqlnRows1 Then /出错提示3.3.4 Delete语句格式如下:Delete From prescribe_recordWhere prescribe_number = :ls_prescribe_numberAnd prescribe_sub_number = :ldc_prescribe_sub_number;If f_SqlErr()0 Then Return 1If Sqlca.SqlnRows1 Then /出错提示3.3.5 游标操作过程如下:Declare cur_storage Cursor ForSelect Nvl(quantity,0),Nvl(retail_price,0)From physic_storage_table Where physic_code = :ls_physic_code For Update;Open cur_storage;If f_SqlErr ()0 Then Return 1Do Fetch cur_storageInto :ldc_quantity,:ldc_retail_price; If f_SqlErr()0 Then Return 1 If Sqlca.SqlCode = 100 Then Exit Loop While TrueClose cur_storage;If f_SqlErr()0 Then Return 13.3.6 动态游标操作过程如下:Declare cur_data Dynamic Cursor For Sqlsa;ls_sql = Select Trim(physic_sorts_code), Trim(sorts_name) + & From physic_sort_dict + & Where super_code = ? Prepare Sqlsa From :ls_sql;If f_SqlErr()0 Then Return -1Open Dynamic cur_data Using :ls_super_code;If f_SqlErr()0 Then Return -1DoFetch cur_data Into :ls_sorts_code,:ls_sorts_name;If f_SqlErr()0 Then Return -1If Sqlca.SqlCode = 100 Then ExitLoop While TrueClose cur_data;If f_SqlErr()0 Then Return -13.3.7 动态SQL语句格式如下:ls_sql = Select * + & From lay_physic_pool + & Where physic_code = +ls_physic_code+ + & And storage_code = +ls_storage_code+ + & For Update Execute Immediate :ls_sql;/对多条数据行锁If f_SqlErr()0 Then Return -13.3.8 没有返回值(out)的存储过程操作过程如下:Procedure sp_set_pres_status(as_pres_no in char,as_pres_status in char)Declare sp_set_pres_status Procedure &For sp_set_pres_status(:ls_pres_no,:ls_pres_status);Execute sp_set_pres_status;If f_SqlErr()0 Then Return 13.3.9 数据库函数与带有返回值(out)的存储过程操作过程如下:Fuction f_get_residence_no(as_sick_id in char) return longDeclare f_get_residence_no Procedure &For f_get_residence_no(:ls_sick_id);Execute f_get_residence_no;If f_SqlErr()0 Then Return 1Fetch f_get_residence_no Into :ll_return,:ls_residence_no;If f_SqlErr()0 Then Return 1Close f_get_residence_no;If f_SqlErr()0 Then Return -1注意事项A.在数据库处理中一定要注意所有数据库操作都要进行容错处理、并发性控制；4、 注释规范:4.1 注释规范总则：4.1.1 在会引起歧义、误会或不易理解、比较复杂的逻辑等类似地方一定要写注释，但并不是注释越多越好，也应注意简洁明了，一目了然的语句或变量就不必加注释，注释能起到提纲挈领和引导解释的作用就可；所采用的语言首选“中文”；4.1.2 PBL库文件、PB对象、全局变量、共享变量、实例变量、常量、函数、事件一定都要写上完整清楚的注释；4.1.3 程序段、局部变量等可依情况写明注释，不一定每处都要写；4.2 注释规范实例：4.2.1 PBL库文件注释：cost_win.pbl/窗口对象login.pbl/登录模块4.2.2 PB对象注释：d_sick_info/病人基本信息数据窗（姓名、费别等）f_get_sys_parm/获取系统表(sys_parm)参数4.2.3 全局变量、共享变量、实例变量、常量注释：若知变量的取值范围也要一并写明Private: String IS_SICK_ID/当前病人ID号 String IS_APPLY_STATUS /单据状态：0.新开;1.扣费;2.执行 DataWindow idw_copy/数据窗拷贝存放对象 Constant String LAY_STATUS_NEW = NEW/配药池新开态4.2.4 函数、事件注释：有以下两种注释风格，若脚