PowerBuilder从入坑到放弃(二)编码规范

前言

上一篇我们从0到1用pb开发了一个helloworld程序,并成功将开发的程序编译打包并且制作了安装包。

程序员最讨厌的莫过于写文档和别人不写注释。

不知道大家会不会和我一样,在找bug时,有段代码,心中不知默默的骂了它多少遍。

哪个sx写的这代码,研究了一段时间发现,原来那sx竟是自己 😔。

无规矩不成方圆,写代码也是一样的,尤其是在团队合作的时候。

要想把代码写得优雅,就必须遵循一定的规则。今天我们就来看看pb开发中应该遵守哪些规范。

一 、变量命名规范

1.1 变量命名规则

变量类型范围简写 + 数据类型简写 +_+ 含义代码 + //注释标明含义

举例说明:

/*1、定义全局变量*/
string gs_orgcode  //定义机构编码
string gs_orgname  //定义机构名称

/*2、定义共享变量*/
string ss_phone 

/*3、定义实例变量*/
string ls_name //定义用户姓名
    
/*4、5、定义值传递变量和引用传递变量*/    
function gf(string v_orgcode,string r_orgname) //根据编号获取名称

以上例子只是以不同变量类型范围内string 类型变量命名举例,具体可根据下面表格中的简写变通

1.2 变量类型范围

--范围 -- 描述 -- 简写
【全局变量】Global 全局变量在整个应用中有效 g_
【共享变量】Shared 共享变量在一个对象及其实例中有效 s_
【实例变量】Instance 实例变量仅在一个对象的实例中有效 i_
【局部变量】Local 局部变量仅在一段子程序或在 script 开始和结束时生效 l_
【值传递的变量】(函数变量) 定义函数时,参数仅传递值,不会被函数改变 (value) v_
【引用传递的变量】(函数变量) 定义函数时,参数将被函数改变(ref) r_

1.2 常见变量类型简写

--数据类型 --描述 --简写
Any 可以保存任何类型的值,包括标准数据类型、对象、结构和[数组 a_
Blob 二进制大型对象,用来存储图片、大文本等信息 bb_
Boolean 布尔型,取值要么true 要么false bl_
Charcharater 单个 ASCII 字符 ch
Date 日期,由完整的年月日组成,格式取决于操作系统的设置 d_
DateTime 日期及时间,用于和数据库的 datatime 类型数据交互 dt_
Decimaldec 有符号十进制数,最大 18 位宽 ,一般用于存储金钱 dec
Double 有符号浮点数,精度 15 位 db
Integerint 16 位有符号整数 Ii
Long 32 位有符号整数 L
Real 有符号浮点数,精度 6 位 r
string 由任何 ASCII 字符组成的字符串 s
Time 24 小时格式的时间值:小时、分、秒以 t
UnsignedInteger 16 位无符号整数 ui
UnsignedLong 32 位无符号整数 ul

二、应用命名规范

应用的命名应使用与该应用的意义相关联的英文字母

app_his 表示医院管理系统

三、pbl 库命名规范

pbl库组织的好坏很重要,它会影响应用开发和维护的容易程度以及应用的性能

3.1 Library 的大小

pb 对 Library 的大小没有限制,但最好小于 1MB ,Library太大的话, pb要花更多的时间去打开和存储对象,这会影响开发的效率

3.2 Library 的数量

尽量用最少的 Library 数量 如果 Library 数量太多而每个 Library 中对象数量太少,搜索路径会
太长,影响运行效率

3.3 Library 的分类组织

pbl 库可按子系统或功能组织,一般应用都包含公共 pbl 库。
每个 pbl库文件命名应该与该文件作用相关联,例如报表 pbl库文件命名为 report.pbl

四、窗口命名规范

w+"_"+与窗口意义相关联的英文字母

注意:总长不得超过 pb的 40 个字符限制

举例:

--窗口名称 -- 注释信息
w_about 关于本系统的版权信息
w_system_error 系统出错提示
w_main 系统主界面
w_report_sheet 报表查询

五、数据窗口命名规范

①数据窗口控件

dw+"_"+ 与数据窗口相关英文字母

② 数据窗口对象

d+"_"+ 与数据窗口相关描述英文字母(普通数据窗口对象) 或者

dddw+"_"+ 与数据窗口相关描述英文字母 (下拉式子数据窗口对象)

举例:

-- 数据窗口控件名称 -- 描述信息
dw_notice 显示通知信息
dw_system_err 显示系统错误信息,被w_system_err 调用
--数据窗口对象名称 --描述信息
d_system_err 显示系统错误信息,是数据窗口dw_system_err的对象
d_goods 显示商品信息
dddw_sex 性别代码表
dddw_tccode 统筹区代码表

六、用户对象

uo+"_"+用户对象相关英文字母

举例:

-- 用户对象名称 -- 描述信息
uo_common_settle 表示该uo 用于通用结算功能
uo_elc_billinvoice 表示该uo 用于处理电子票据功能

七、常用控件

控件简写+"_"+功能描述英文字母

-- 控件名称 -- 控件缩写 -- 控件命名例子
CommandButton cb cb_exit
PictureButton pb pb_thank_info
CheckBox cbx cbx_age_show
RadioButton rb rb_sex
StaticText st st_user_id
Picture p p_user_img
GroupBox gb gb_detail_info
Line ln ln_h_separator
Oval oval oval_used_flag
SingleLineEdit sle sle_name
MultiLineEdit mle mle_book_comments
RichTextEdit rte rte_student_answer
EditMask em em_tel
DropDownListBox ddlb ddlb_type
DropDownPictureListBox ddplb ddplb_photo_preview
ListBox lb lb_department_name
PictureListBox plb plb_user_identification
ListView lv lv_all_user
TreeView tv tv_customers
TabPage tpg tpg_ordinary_super
Tab tab tab_super
DataWindow dw dw_user_info
OLE ole ole_word_doc

八、函数命名规范

函数类型+f+“_”+函数意义相关联的英文字母

--函数类型 --函数类型简写
全局函数 g_
窗口函数 w_
菜单函数 m_
用户对象函数 u_

举例:

-- 函数名称 --描述信息
gf_getOrgInfo 全局函数,用于获取机构信息
wf_getUserInfo 窗口函数,用于获取用户信息
uf_query_username 用户对象函数,用于查询用户姓名

九、关于注释

9.1 窗口open事件前说明

/* ======================================================= */
// 窗口中英文名称:
// 窗口作用:
// 作者:
// 日期:
/* ======================================================= */

9.2 在事件脚本( Script)之前应说明

/* ======================================================= */
// 脚本作用:
// 输入参数及数据类型:
// 返回参数及数据类型:
// 全局函数及其用途:
// 全局变量及其用途:
// 作者:
// 日期:
// 修改人的姓名:
// 修改日期:
// 修改原因:
/* ===================================================== */

9.3 脚本中的注释

①单行脚本程序注释:

// 注释文本

②脚本的程序段注释:

/* ================================== */
//
// 注释文本
//
/* ================================== */

③ 变量注释

数据类型 变量名 //注释

9.4 在函数、存储过程等脚本( Script)之前应说明

/* ======================================================= */
// 函数名称:
// 参数解释:
// 功能描述:
// 调用举例:
// 最初作者:
// 编写日期:
// 返 回 值:
// 变量情况:
// 修 改 人:
// 修改日期:
// 修改原因:
/* ======================================================== *

十、代码编写规范

脚本的书写应该层次清楚,以便于阅读

  • 用分层缩进的写法显示嵌套结构的层次
  • 在注释段与程序段,以及不同逻辑的程序段之间插入空行
  • 每行至多只写一条语句,当需要滚动显示时应该分行书写。一条语句需要在多行书
    写时,用&进行连接

10.1 流程控制写法

用分层缩进的写法突出显示嵌套的层次结构

例如:

For i = 1 To 100
    For j = 1 To 50
		For k = 1 To 200
			Matrix[i, j, k]=1
		Next
	Next
Next

10.2 数据库相关

sqlca的连接语句connect在应用Open事件中完成,其disconnect在主应用的
close事件中完成,其余任何pbl中均不能有disconnect语句

② 要连接多个数据库,需要用Create创建对象,比如, sqlsyb,连接用 connect using sqlsyb, 处理完毕后用 disconnect using sqlsyb, 并且用 destroy sqlsyb释放资源

③所有sql语句均需判断返回结果(包括selectcommit语句)

If sqlca.sqlcode = -1 Then
    // 错误处理程序
    // 跳出
Else
    // 正常
End If

10.3 代码块之间留一行

If <condition1> Then
	<statementblock>
End If
    
For <varname>=<start> To <End> Step <increment>
	<statement_block>
Next

10.4 单行注释与当前script程序的缩进位置对齐

//这是对condition1的注释
If <condition1> Then
	//这是对condition2 的注释
    If <condition2> Then
		//这是对action1的注释
		<action1>
	End If
End If

10.5 代码缩进用tab

缩进应以Tab键实现,不得采用空格

10.6 变量采用小写格式

  • 变量全部用小写

    string ls_name
    
  • 一个变量一行,每个变量必须注释

    string ls_name   //用户姓名
    string ls_sex    //用户性别
    int li_age    //用户年龄
    
  • 通常情况下,变量的后半部分尽量用数据库字段名

  • 变量声明全部在脚本之前声明完毕

  • 对象名采用小写,属性、关键字、保留字和内置函数均采用首字母大写格式

    w_cont_de.Visible = True
    m_mdi.m_file.m_print.Enabled = False
    

10.7 字符串排版

连接起来的字符串超过了两行的长度时,使用 +&,每次均
采用缩进格式。字符串的随后部分应该再次缩进

ls_msg = "连接数据库失败!错误信息为: ~r~n" +&
    	 Sqlca.SqlErrText +&
		 "请与系统管理员联系"

10.8 PB关键字书写

首字母大写,这样看起来层次清晰

// 举个栗子
This,Parent, ParentWindow, True, False, Return, Halt,Close

10.9 PB内部函数及属性

采用每个字首字母大写,这样看起来层次清晰

//举个栗子
sle_user.Text
dw_1.SetTransObject(Sqlca)
Sqlca.SqlErrText

10.10 SQL语句书写

SELECT name, sex, dept_id
	INTO :ls_name, :ls_sex, :ls_dept_id
FROM employee
WHERE emp_id = :ls_emp_id;

10.11 goto跳转语句

程序中应避免出现 goto 跳转语句 ,如果必须要使用,需要详细注释说明

10.12 游标模块

注意:游标命名规则: Cur + _ + 名称。

Declare Cursorname Cursor for
		Select语句
Open Cursorname;
fetch Cursorname into <variables>
Do While Sqlca.Sqlcode = 0
	<statementblock>
	fetch Cursorname into <variables>
Loop
Close Cursorname

10.13 存储过程调用

注意:存储过程命名规则: Pro + _ + 名称。

declare Procedurename procedure For StoredProcedureName
		: Value1,: Value2...;
execute Procedurename;
fetch Procedurename into <variables>;
close Procedurename;
commit;

10.14 操作符前后应留一空格

所有操作符(包括等号)前后应留一空格,使程序看起来更清晰

ls_msg = ls_title + ls_error

10.15 循环中使用函数

仅当绝对需要时才在循环结构体中使用函数调用,也就是说,仅当函数的返回值依赖于循环迭代的值时才使用函数调用

① 正例
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    

10.16 条件判断表达式

条件判断表达式中,变量和固定取值的比较尽量不要使用<>进行判断,尤其数据来自数据库时,以保证程序的扩充性。

比如,前期设计中 1 代表男、 2 代表女,使用 var=2 比var<>1 的判断有更好的可扩充性

十一、控件使用规范

  • 应尽量为所有控件使用有意义的名称,重要控件不允许使用 pb_1 之类无明确意义的名称
  • 大号字体:各窗口控件字体为Arial,字号为12号,字色为黑色。小号字体:各窗口
    控件字体为宋体,字号为9号,字色为黑色。
  • 显示控件和输入控件底色分开,显示控件为灰色(窗口颜色),输入控件为白色
  • 输入区和显示区分别放置
  • 按钮排列紧凑,在窗口右侧纵向排列时靠上放置;在窗口下方排列时靠右放置,因为左撇子操作者毕竟是少数
  • 各字符类控件对齐方式为左对齐;数字类控件为右对齐,且必须按所需格式设置
    Format 属性;日期控件必须保证能完整显示所需日期格式,应用yyyy-mm-dd风格
  • CommandButton控件的推荐高度为104

11.1 静态文本框

命名规则: st +_ + 名称(若为label可不改名)

外观规定如下

  • 背景色: buttonface;

  • 前景色:黑色

  • 边 框:无

  • 高 度: 72

    建议在其后加上全角冒号(: )

11.2 单行编辑框

命名规则: sle +_ + 名称

( 1)外观

  • 背景色:白色
  • 前景色:黑色
  • 边 框: 3D Lowered
  • 高 度: 72

( 2)程序说明

  • 响应事件建议自定义 Keydown 事件,尽量不要用 Modify 事件
  • 当获得焦点时控件背景变为深蓝色,字体颜色变为黄色,失去焦点时还原默认颜色

11.3 命令按钮

命名规则: cb +_+ 名称

( 1)外观

  • 高度:对于小号字体(宋体9号)为92;对于大号字体( Arial 12号)为108
  • 宽度:对于小号字体(宋体9号)为325;对于大号字体( Arial 12号)为402

( 2)说明

命令按钮控件不要使用 cb_1 之类无明确意义的名称(尤其在窗口中这类控件比较多时,
可能令人分不清各个控件的作用)

11.4 图像按钮

钮命名规则: pb + _ + 名称

外观规定如下

  • 尺寸:用图像原始尺寸
  • 图像:按钮的有效与无效采用不同的 bmp 图像以示区别

注意: 尽量不用图形按钮,而用命令按钮

11.5 复选框

命名规则: cbx + _ + 名称

外观规定如下:

  • 背景色: buttonface
  • 前景色:黑色
  • 边 框: 3D Lowered
  • 高 度: 92;
  • 位 置:标签在右

11.6 单选按钮

命名规则: rb + _ + 名称

( 1)外观

  • 背景色: buttonface
  • 前景色:黑色
  • 边 框: 3D Lowered
  • 高 度: 92
  • 位 置:标签在右

( 2)程序说明

  • 单选按钮最好与组合框配合使用

11.7 组框

命名规则: gb + _ + 名称

外观规定如下:

  • 背景色: buttonface;
  • 前景色:黑色;
  • 边 框: 3D Lowered

11.8 屏蔽编辑框

命名规则: em + _ + 名称

( 1)外观

  • 背景色:白色;
  • 前景色:黑色;
  • 边 框: 3D Lowered。

( 2)程序说明

  • 响应事件建议用自定义 Keydown 事件,尽量不要用 Modify 事件。
  • 当获得焦点时控件背景变为深蓝色,字体颜色变为黄色,失去焦点时还原默认颜色

11.9 下拉列表框

命名规则: ddlb + _ + 名称

外观规定如下:

  • 背景色:白色;
  • 前景色:黑 色;
  • 边 框: 3D Lowered

11.10 应用

命名规则: app + _ + 应用名

  • 为应用选择一个图标,以便在运行时标识应用。
  • 在 Open 事件中声明 SQLCA 全局变量和打开应用主窗口。
  • Closequery 事件中编写退出应用之前的处理程序。
  • SystemError 事件中编写系统出错的处理程序

11.11 窗口

命名规则: w + _ + 窗口名

  • 主窗口采用 main 窗口类型,子窗口一般采用 Popup窗口类型,无控制菜单,无最大
    化最小化按钮,不可改变大小。若为一般性提示窗口,用 response 窗口类型。
  • 窗口以 buttonface 颜色为背景颜色
  • 重要的菜单选项设置 Toolbar 功能
  • 窗口上下左右四周应至少留出两个网格,而不得将对象填满整个窗口

11.12 菜单

命名规则: m + _ + 菜单名

菜单项 MenuItem 的名称以该菜单项在整个菜单中的物理位置分层次命名

MenuItem 位于整个菜单的第三列第二行,则命名为 m_32;文件菜单下的“关
闭”菜单项,命名为 m_file_close

11.13 数据窗口对象

命名规则: d + _ + 功能含义

  • 打印用数据窗口的背景色为白色,题目为16号字,内容为11号字,显示比例为75%
  • 显示用数据窗口的背景色原则上为 buttonface, 可视窗口制作是否美观的实际情况而定
  • 白色数据窗口各列显示框高度为72
  • Tabular 和 Grid 风格数据窗口,无表头时列名文本边框为 3D Raised。 Detail 区为 3D
    Lowered,背景色原则上为白色。 Grid 风格数据窗口一般不出现线条

11.14 数据窗口控件

命名规则: dw + _+ 功能含义

数据窗口边框原则上为 3D Lowered,也可以使用 none 外加 group

11.15 用户对象命名

命名规则: uo + _ + 功能含义

公共对象对应以上各控件规范制作

十二、错误处理

对错误的处理和状态监测程序实行标准化,这有几方面的原因:

  • 要在整个应用中统一处理;
  • 减少偶然漏掉特有处理的可能性;
  • 减少日后进行软件维护时的不必要的麻烦

以下几个方面的检查可以考虑用标准的方法处理:

  • 连接错误;

  • 连接库存取错误;

  • 数据录入错误;

  • 程序执行错误。

    程序执行出错处理必须明确指出出错的原因或者可能。
    数据库操作出错必须指出数据库错误代码( SQLCA.SQLCODE)以及数据库错误说明
    SQLCA.SQLERRTEXT),即下面的这段代码必须在数据库操作出错处理中:
    "rnrn 错误码: " + string(SQLCA.SQLCODE) &
    + "rnrn 出错信息: " + SQLCA.SQLERRTEXT )

十三、版本控制

① 软件版本号标准为 a . b,其中 a 和 b 为 0 到 99 之间的数字

② 当 a 大于 1 并且 b 为奇数时, 表示当前版本为处于开发、 测试阶段的版本, 定义为“开
发版”;当 b 为偶数时,表示当前版本为稳定的、可实际运行的版本,定义为“稳定版”

③ 当软件开始开发时,确定版本号为 0.1;随着软件开发的进度,版本号随着每一次主
要功能的完善而变化,最高达到 0.99

④ 软件初步开发完成后,经过软件开发小组内部测试,初步能够完成软件需求提出的
业务规范和技术要求,软件基本能正常运行,此时,确定该软件版本号为 1.0 Beta x ,这意
味着软件可以投入实际应用测试,其中 x 代表测试的次数

⑤ 当软件的 1.0 Beta x 版本推出并经过用户实际应用或者试运行测试后,此时,确定该
软件版本号为 1.0 RC。这意味着软件可以投入实际应用运行

⑥ 当软件的 1.0 RC 版本投入实际应用运行达到某一时限后,则认为该版本已经稳定,
可以完全正常地使用了,这时,确定软件的版本号为 1.0,这意味着软件开发完成,可以投 入实际应用和推广

⑦ 当软件进行升级时,如果功能变化不大,则次版本号变化如果软件功能发生重大变化时,主版本号变化

十四 小结

以上从变量命名规范、pb的各种控件命名规范、代码书写、注释、错误处理、版本控制等方面说了日常工作中

使用pb开发应遵守的一些规约。

当然了,上面规范也不是必须的,你所在的团队也会有自己的一些规约。

本期内容到此就结束了,希望对你有所帮助。我们下期再见 (●'◡'●)

参考文献

  • [√] PowerBuilder 9.0 实用解析
  • [√] Poweruilder9.0精彩编程百例
  • [√] PowerBuilder 10.0 应用基础与实例教程
  • [√] PowerBuilder高级编程及其项目应用开发

热门相关:恭喜你被逮捕了   花月颂   变身蜘蛛侠   变身蜘蛛侠   前任无双