控件编程规范

一、 书写格式

a.   用分层缩进的写法显示嵌套结构的层次。

b.   在注释段与程序段，以及不同逻辑的程序段之间插入空行。

c.   每行只写一条语句，当需要滚动显示时应该分行书写。

二、 流控制

流控制首先应遵守PowerBuilder语法规范，且用分层缩进的写法突出显示嵌套的层次结构，例如：

For i = 1 To 100

        For j = 1 To 50     

                      For k = 1 To 200

                                Matrix[i，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 Then

                          

                  End If

                   For = To Step

                           

                  Next

（2）把单行注释与当前script程序的缩进位置对齐：

                  //This is a comment For condition1

                  If       Then

                           //This is a comment For condition2

                           If          Then

                                    //This is a comment For 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 = "连接数据库失败！错误信息为：~r~n" &

                      + 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

                  Do While Sqlca.Sqlcode = 0

                          

                           fetch Cursorname into        

                  Loop

                  Close Cursorname

        光标命名规则：“Cur” + “_” + 名称。 

（2）调用数据库存储过程的编程约定如下：

             declare Procedurename procedure For StoredProcedureName

                                     ：Value1，：Value2......；

                  execute  Procedurename；

                  fetch Procedurename into ；

                  close Procedurename；

                 commit；

      存储过程命名规则：“Pro” + “_” + 名称。

   有些系统存储过程（例如：sp_droplogin）不能当做一个事务提交，为了执行它，就必须先置事物对象的AutoCommit属性为True，当存储过程执行完毕后再将事务对象的AutoCommit属性置为False。

（3）在每一个SQL语句之后必须判断SQL语句执行成功与否，成功则继续，不成功则做相应处理并给出一条提示信息。

 If Sqlca.SqlCode <> 0 Then

    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_selected

……

Next

不使用下述方法：

For i = 1 To lb_1.TotalSelected()

……

    Next

4. PB中的任何一个窗口都要有注释说明
一般在窗口的Open事件中对窗口的功能进行全面的介绍，以便维护人员可以很清楚地知道窗口的功能和维护要点。其格式可参见前面的说明。

5. 表的操作
在程序中涉及多个表的操作时，需严格按照各项目组“表操作顺序一览表”规定的顺序对表进行操作，以防发生锁表现象。