PB软件设计技术规范

PB 软件设计技术规范 修订本 1 软件界面风格 1 1 窗口 1 主界面 采用巨龙定制的标准的 管理信息系统 程序主界面 2 分辨率 程序窗口设计的分辨率为 800 600 或 640 480 窗口高宽比例应该与屏幕的比 例一致 3 窗口模式 分清有模式窗口 对话框 和无模式窗口 对话框 有模式窗口 对话框 在 应用程序继续之前必须由用户关闭 无模式窗口 对话框 允许用户在不取消 或不移去窗口 对话框 的情况下 显示并返回到另一任务 4 窗口标题 应能反映该窗口的功能的简单概括性文字 不能太长 5 颜色 窗口的背景颜色使用巨龙指定背景或微软缺省颜色 6 字体 在 Window 95 中开发推荐使用宋体 9 号 在 window NT 中开发推荐使用宋体 9 号 7 控件 控件位置摆放适当 特别是按钮位置摆放 上 下等 数据窗是否允许横滚动 条出现 数据窗对象颜色设置 字段颜色和状态 录入 修改数据窗对象中非 空字段和不允许获得焦点字段的体现 适当形象图形的使用 常用按钮名称的统一规定 新增 保存 修改 条件 查询 打印 打证 照片 浏览 确定 取消 复 位 关闭 退出 返回 预览 打印设置 前翻 后翻 业务操作按钮 按扭的命名简洁 形象 8 方便用户 录入界面要考虑用户录入的方便 要求能使用回车键 TAB 键在单元格间行进 考虑 ESC RETURN 键的缺省实现 9 提示信息 窗口状态条和 TAG Microhelp 提示信息 1 2 菜单标准 如果菜单命令在被执行之前还需要其他信息 例如 弹出其他对话框 那么 应该在菜单标题后面加上省略号 例如 另存为 A 所有的菜单都应该有键盘访问入口 同一层菜单不应有重复的键盘访问入口 最好只有两层菜单 多于一层子菜单的情况可以考虑用对话框代替 菜单名称中文在前 英文字母在后 并带括弧和下划线 1 3 工具栏 工具栏应可移动 功能相关的应绑定成组 1 4 图标 系统图标 收集定作 1 5 字符串 统一的快捷键 一致的提示信息 包括错误处理 1 6 输出 1 全系统有明确的使用 信息 出错提示 2 用户的查询 统计结果分为屏幕显示和打印输出 屏幕显示要求数据足够 详实 打印输出要求可由用户调整输出数据项 还可定制打印输出格式 3 打印 如整张报表为空 没有记录 则不进行打印 4 只要存在一个输入或查询 DATAWINDOW 均应有打印功能 1 7 其他 1 标准的 About 关于 对话框 Splash 对话框 口令验证对话框 2 最大化按钮必须确有放大作用 关闭按钮仅作为缺省或备用方式 另在窗 体中应有 确认 或 取消 或 关闭 按钮 3 反馈给用户的说明文字的要求 避免使用计算机用语 消息限制在 2 3 行 内 避免用责怪用户的措辞 多行消息的文本左对齐 避免在说明文字中出现 错别字 4 帮助菜单中加入 关于 A 项 5 删除记录时提示 是否要删除 选择 是 否 6 如有修改记录将要退出时或要进入查询条件输入状态时均要提示 是否要 保存 选择 是 否 取消 7 对重要操作如初始化 计算等影响面大的要提示 操作 后果 是否进 行操作 选择 是 否 8 对键盘的支持 友好的用户界面应有很好的键盘支持 应用程序应该支持 常用的键盘操作 所有菜单上的命令都是可以通过键盘来访问 9 所有的 WINDOW 均应有标题 标题内容为当前处理内容 2 软件编码规范 程序设计的标准是结构清晰 可读性好 这样可便于测试和排除程序故障 能 够有效地在开发期间消除绝大多数在程序中掩藏的故障 大大提高软件的可靠 性 另外可方便对他进行修改 扩充和移植 程序的可维护性好 2 1 基本命名法则 使用统一编码约定集的主要原因 是使应用程序的结构和编码风格标准化 以 便于阅读和理解这段编码 好的编码约定可使源代码严谨 可读性强且意义清 楚 与其它语言约定相一致 并且尽可能的直观 PB 应用程序中的命名标准主 要分为三个方面 控件命名标准 变量命名标准以及函数 过程 命名标准 在 PB 代码中声明的过程 变量和常数的名字 必须遵循以下这些规则 它们必须以字母开头 它们不可以包含嵌入的句号或者类型声明字符 规定数据类型的特殊字符 它们不能超过 255 个字符 控件 窗体 类和模块的名字不能超过 40 个字 符 它们不能和受到限制的关键字同名 受到限制的关键字是 PB 使用的词 是语言的组成部分 其中包括预定义语句 比如 If 和 Loop 函数 比如 Len 和 Abs 和操作符 比如 Or 和 Mod 2 2 常量及变量命名原则 变量应该总是被定义在尽可能小的范围内 在 PB 的应用程序中 只有当 没有其它方便途径在窗体之间共享数据时才使用全局变量 当必须使用全局变量时 在一个单一模块中声明它们 并按功能分组 给 这个模块取一个有意义的名称 以指明它的作用 常量及变量的命名规则为 变量范围前缀 对象或变量数据类型 变量 常 量 名主体 在程序中 所有的变量都应该声明 常 变 量名使用缩略语时 要确保它们在整个应用程序中的一致性 在一 个工程中 如果一会儿使用 Cnt 一会儿使用 Count 将导致不必要的混淆 2 2 1 变量范围前缀 下表列出所有 PB 语言的变量范围修饰符 变量范围前缀 GlobalG ShareS InstanceI LocalL ArgumentA 2 2 2 变量数据类型 数据类型前缀 AnyA BlobBlb BooleanB CharCh CharacterCh DateD Date TimeDt DecDec DecimalDec DoubleDbl IntI IntegerI Long L RealR StringS TimeT UnitUi UlongUl UnsignedIntUi UnsignedintegerUi Unsigned Long Ul Powerobjectpo 2 2 3 常 变 量名主体 常 变 量名的主体是大小写混合的 每个单词的首字母大写 要求能反映常 变 量的意义 而且变量名应该是 动宾结构 例如 li UserListMax 对用户列表的最大限制 整数值 本地到模块 gs NewLine 新行字符 字符串 应用程序全局使用 给常量分组 变量和定义的常量应该按功能分组 而不是分散到单独区域或特 定文件中 PB 变量命名由该变量被访问的范围和数据类型组合成前缀 2 3 函数及过程名的命名约定 函数及过程名的命名基本与变量的主体名一样 另外除了全局变量 应该是不 被传递的 过程和函数应该仅对传递给它们的对象操作 在过程中使用的全局 变量应该在过程起始处的声明部分中标识出来 此外 应该用 ByVal 将参数 传递给过程及函数 除非明显地需要改变已传递的参数值 2 4 对象 含控件 编码约定 为了容易识别不同的对象类型 建议使用一致的对象前缀命名对象 窗口控件命名 以 PB 提供的缺省名为前缀 加上该控件的具体操作含义命名 如 cbx draf cb ok dw data ddlb agents ddplb orders em phone 等等 标准类前缀 标准类命名前缀 ConnectionCn ContextInformationCi ContextKeyWordCkw DatastoreDs DynamicStagingAreaDsa DynamicDescriptionAreaDda ErrorErr InetIent InterResultIr MailSessionMs MessageMsg OLEObjectOleobg OLEStorageOlestg OLEStreamOlestr PowerOobjectPo PipelinePl ProfillingPrf ServiceSvc TimingTmg TrangcationTr Transporttrp 类名 对象名称前缀举例 Data PpipelinePipe Pipe invoice Data Window ObjectDw Dw clint DrawDownDataWindowDddw Dddw state Function global F F display Function window Wf Wf input MenuM M main ProjectP P tracking ProxyPry Pry custrom QueryQ Q agent StructureS S employee User ObjectU WindowsW W ancestor ReportR R list 其他控件的命名 对于上面没有列出的控件 应该用唯一的由三个字符组成的 前缀使它们标准化 以保持一致性 另外 对于程序中自定义的控件 也应该 用唯一的由三个字符组成的前缀使它们标准化 并在该程序中保持一致 只有 当需要澄清时 才使用多于三个字符的前缀 小组中通用的自定义的控件 应 该单独提交 指定相应的命名标准 2 5 格式化编码约定 2 5 1 代码注释约定 所有的过程和函数都应该以描述这段过程的功能的一段简明注释开始 这段例 程干什么 这种描述不应该包括执行过程细节 它是怎么做的 因为这常常 是随时间而变的 而且这种描述会导致不必要的注释维护工作 甚至更糟 成 为错误的注释 代码本身和必要的嵌入注释将描述实现方法 当参数的功能不明显且当过程希望参数在一个特定的范围内时 也应描述传递 给过程的参数 被过程改变的函数返回值和全局变量 特别是通过引用参数的 那些 也必须在每个过程的起始处描述它们 函数头注释块应该包括下列节标题 节标题注释描述 Purpose该过程完成什么 而不是怎么完成 Assumption列出每个外部变量 控件 打开文件或其它不明显元素 Effect列出每个被影响的外部变量 控件 或文件及其作用 只有当 它不明显时 Input每一个可能不明显的参数 参数分别在单独的行上 并嵌入注 释 Return返回 函数返回值的说明 记住下列几点 每一个重要变量的声明应该包括一个嵌入注释 来描述该变量的使用 变量 控件及过程的命名应该足够清楚 从名字就可以判断他们的作用 使得只有复杂的执行细节才需要嵌入注释 2 5 2 格式化代码 变量命名放在程序的前端 并按类型分开 建议保留字第一个字母大写 如 String ls getstring ls getstring This Gettext Pb 函数第一个字母大写 函数较长且具有分段性含义时 适当把其中字母大写 如 ls getfile ProfileString c pb ini pb pb None dw mian AcceptText 循环 分支 判断语句中 采取层层缩进的风格如下所示 For ll num 1 to ll count If ll num 5 Then Ls aa String ll num 5 Return ls aa Elseif ll num 10 Then End if Next Do While ll num 20 Ls value ll num ll num 5 Loop Choose Case ll num Case 1 Case 2 End Choose 程序行不要太长 以屏幕能显示为基准 太长时使用 号换行 换行程序退一 个位开始 如 If Trim dw data GetitemString 1 2 Column Or Trim dw data GetitemString 1 2 Name Then 程序运算符前后建议用空格分阁 如 ls aa dw main Gettext 而不要 ls aa dw main Gettext 2 5 3 PB 程序注释规范 每个 PBL 库 每一个对象必须有注释 说明其主要功能 在代码中 以 为段注释 为行注释 代码中每一个功能段必须要有段注释 在功能段开始处开始注释 结束处标明 该功能结束 为了避免交叉注释混乱 可以在注释开始加 注释段 1 等说明 只放在代码行的最后面 对当前行的代码进行说明 如 注释段 1 取得数据窗对象的各种属性 取得字段类型 注释段 2 判断某字段是否为日期型属性 注释段 2 结束 返回结果 注释段 1 结束 变量定义放在程序首端 按各功能段分开注释 如果有多个功能段公共使用的 变量 则放在最前面 并将变量含义注释说明 如 公共变量定义 String ls column name ls column value 数据窗对象列名 数据 Long ll row ll rowcount 当前行 行总数 功能 A 变量定义 Long ll I String ls col 附代码说明 变量定义模板 以下代码版权为厦门巨龙软件公司所有 严禁非法拷贝 总体功能说明 功能模块列表说明 模块 A 模块 B 变量定义 公共变量定义 功能 A 变量定义 功能 B 变量定义 变量定义结束 1999 07 每一个全局变量必须有注释说明 说明其作用和应用大概范围 每一个实例变量和共享必须有注释说明 说明其作用 每一个函数必须要有详细的注释 在函数代码前端必须进行详细说明 函数的功能 函数的参数 函数返回值和错误处理 如 函数 f col nullcheck 用于校验数据窗指定列中是否有值 参数 1 adw data datawindow 需要校验的数据窗 2 as col string 需要校验校验的列 返回值 1 成功 1 有空值 2 列名列表有误 Char n n is the number of characters Date DateTime Decimal n n is the number of decimal places Number Time Timestamp 2 5 4 SQL 语句变量定义和注释规则 SQL 语句中变量当作局部变量 定义方式以 L 加变量数据类型为前缀 即如果 使字符或字符串则为 Ls 数值型为 ln 日期型为 ld 注释规范与 PB 代码类似 每段 SQL 开始时要用 注释该段代码的功能和作 用 如建表则要说明该表名称和简单的描述 视图则说明名称外 还要注明视 图涉及的表 在多级视图 即视图中套用视图 中 各个视图必须说明它们之 间的关联关系 而最终视图必须指明与前台对应的统计报表或相关数据窗对象 如 VW A 视图由 VW 1 VW 2 VW 3 三个视图组成 而 VW 1 由表 T 1 得到 VW 2 由表 T 2 得到 VW 3 由表 T 3 得到 那么 VW 1 VW 2 VW 3 必须 说明由 T 1 T 2 T 3 得到 同时也须说明它们是组成 VW A 的 而 VW A 必须说明由 VW 1 VW 2 VW 3 得到 同时说明 VW A 与前台数据窗对象 的对应关系 在过程 触发器 函数 软件包中 则要说明其功能和作用的表或视图 如果 有参数则要说明其参数的意义 行注释加在改行的最后面 2 6 键盘及快捷方式约定 键盘是用户与系统相互交流的主要工具之一 为了使系统程序符合 Windows 标 准程序微标 为了更加统一 方便用户键盘操作 特对编程人员做如下约定 键盘上的键的功能尽量与 Windows 系统一致 避免使用操作系统保留的键或键的组合 以下列附表为参考标准 附表一 以下键涉及到数据 对象的浏览 或称目标移动键约定 键 名 光标移动大小加按 CTRL 键后的光标移动大小 LEFT ARROW向左移动一个单位向左移动数个单位 RIGHY ARROW向右移动一个单位向右移动数个单位 UP ARROW向上移动一个单位向上移动数个单位 DOWN ARROW向下移动一个单位向下移动数个单位 HOME移动到首行移动到最前面一行 END移动到尾行移动到最后面一行 PAGE UP上翻一页 一屏上翻数页 PAGE DOWN下翻一页 一屏下翻数页 TAB移动到下一个域注 加按 SHIFT 键 反方向移动 附表二 Windows 系统标准的常用快捷键 键 名 功 能 说 明 CTRL CCOPY CTRL OOPEN CTRL PPRINT CTRL SSAVE CTRL VPASTE CTRL XCUT CTRL ZUNDO F1显示联机帮助窗口 SHIFT F1激活联机帮助 SHIFT F10显示右键菜单 SPACEBAR选择 与鼠标单击有同样功能 ESC取消操作 ALT使能或者关闭菜单条 ALT TAB显示下一个主窗口 ALT ESC显示下一个窗口 ALT SPACEBAR显示窗口的的弹出式菜单 ALT HYPEN显示 MDI 窗口的自窗口 ALT ENTER显示所选择对象的属性页 ALT F4关闭当前活动窗口 ALT F6切换到另一程序的下一个窗口 ALT PRINT SCREEN捕捉当前窗口的图象到剪贴板 PRINT SCREEN捕捉桌面的图象到剪贴板 CTRL ESC激活 Start 按扭 CTRL F6显示 MDI 窗口的下一个子窗口 CTRL TAB显示 MDI 窗口的下一个窗口页 CTRL ALT DEL系统保留 附表三 以下键为 Windows 系统使用的功能键 应尽量避免使用 键 名 功 能 说 明 APPLICATION显示被选中对象的弹出式菜单 WINDOW显示 开始 菜单 WINDOW F1显示 Windows 系统的主帮助窗口 WINDOW TAB激活下一个应用程序窗口 WINDOW E浏览 我的电脑 WINDOW F查找文件或文件夹 WINDOW CTRL F查找计算机 WINDOW M缩小化所有应用程序的窗口 SHIFT WINDOW M取消缩小化所有应用程序的窗口 WINDOW R显示 运行 对话框 WINDOW BREAK系统保留 WINDOW number系统保留 附表四 以下为 Windows 系统使用的键的特殊处理方式 原则上不用 键 名 功 能 说 明 左 ALT SHIFT NUMLOCK锁住鼠标 按 SHIFT 键连续 5 次锁住粘贴键 按右 SHIFT 键 8 秒以上锁住过滤 慢速 重复等功能 按 NUM LOCK 键 5 秒以上锁住粘贴键功能 3 程序功能与性能要求 3 1 业务功能要求 1 业务数据的输入应有有效性检查 下列情况之一应提示 输入非法 中文姓名项输入字母 数字 符号 空格等 英文姓名项输入汉字 数字 符号等 数字项输入字母 符号 汉字等 日期项输入非法日期或太早 太晚等不可能的日期 明显有前后差别的两个日期项 D1D2 需求中规定不能为空的项输入空 需求中规定应同时为空或同时不能为空的项目输入部分空 部分非空 输入比字段长度更长的值 不同数据段决定相关项目意义的数据 如身份证有效期对年龄 十年 16 26 二十年 26 46 长期 46 输入年龄介于 15 16 26 27 46 47 的日期 需求中有规定内在关系的项输入违反其关系的数据 如身份证号检验码与 其它码的关系 身份证号与性别 出生年月日的关系 家庭关系与性别的 关系 需求中规定有限制条件 可能因业务而不同 的项目输入超出限制以外的 数据 违反常识的不合理输入 如身高 300cm 2 保证业务的完整性 指业务功能执行成功或中途失败应保证业务数据完整 性 一致性 3 批量业务对业务数据的正确处理等 4 业务 操作 流程的正确性 5 业务流程对数据作用的准确性 完整性 6 数据输出如报表 套打表单与 需求分析 等格式相符合 7 需要统计或计算的输出的公式 算法的正确性 8 业务数据的输入界面应有方便性设置 减少用户输入动作数量 防止输入 错误 如 输入前系统一些项目的缺省设置 输入前系统一些项目的范围限制 表码过滤 输入某些项目后系统一些项目的缺省设置 输入某些项目后系统一些项目的范围限制 表码过滤 表码项目应使用类库中的诱导输入 不必输入的项目予以屏蔽或隐含 录入新记录时光标落在第一个录入项 TAB 顺序按界面物理顺序 消除冗余输入 如输入单位由系统指定并清楚提示 如身高单位为 CM 9 菜单名和它打开的对应窗口名应当一致 10 浏览性数据窗应有一个指示当前记录的指针 11 同一屏幕中菜单快捷键 按钮快捷键 功能键不应重复 12 所有用户输入的项目都应有对应查询模块把它们查出 13 数据保存成功与否都要给予提示 3 2 通用功能要求 通用功能指系统各个模块共同使用的功能模块 包括查询 排序 过滤 查找 打印设置等 1 通用功能完成的正确性和一致性 2 通用功能界面和使用方式上的一致性 3 3 界面要求 详见第一章 1 界面的美观 颜色布局符合合理性 一致性 2 快捷键和功能执行方式应有一致性 3 同一屏幕中菜单快捷键 按钮快捷键 功能键不应重复 4 按钮和标签的说明性文字应具有自明性 5 操作方便 易理解 易学习 易操作 减少用户输入动作的数量 6 同时考虑键盘与鼠标 在数据输入时不需要频繁切换 7 菜单名和它打开的对应窗口名应当一致 8 浏览性数据窗应有一个指示当前记录的指针 9 如有要求此软件和其它相关软件具有界面一致性 应达到要求 10 系统提示能引导用户进行正确操作 并对操作结果给出明确的提示 11 帮助信息的完备性 准确性 3 4 故障处理要求 无论多么的仔细 应用程序都可能产生错误 应用程序应包含错误处理 特别 是在与硬件设备的交互 数据库的操作等 Err 对象 Err 对象包含有关运行出错的信息 程序中的非法操作