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_ |
Char 或charater |
单个 ASCII 字符 | ch |
Date |
日期,由完整的年月日组成,格式取决于操作系统的设置 | d_ |
DateTime |
日期及时间,用于和数据库的 datatime 类型数据交互 |
dt_ |
Decimal 或 dec |
有符号十进制数,最大 18 位宽 ,一般用于存储金钱 | dec |
Double |
有符号浮点数,精度 15 位 | db |
Integer 或 int |
16 位有符号整数 | I 或i |
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事件中完成,其disconnec
t在主应用的
close
事件中完成,其余任何pbl
中均不能有disconnect
语句
② 要连接多个数据库,需要用Create
创建对象,比如, sqlsyb
,连接用 connect using sqlsyb
, 处理完毕后用 disconnect using sqlsyb
, 并且用 destroy sqlsyb
释放资源
③所有sql
语句均需判断返回结果(包括select
, commit
语句)
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高级编程及其项目应用开发