PowerBuilder从入坑到放弃（二）编码规范 - xiezhr

上一篇我们从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 变量类型范围

1.2 常见变量类型简写

二、应用命名规范

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

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 个字符限制

五、数据窗口命名规范

①数据窗口控件

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

② 数据窗口对象

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

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

六、用户对象

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

七、常用控件

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

八、函数命名规范

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

九、关于注释

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语句均需判断返回结果（包括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高级编程及其项目应用开发