PB命名规范.doc

第1章 - 应用系统源程序基本规范1. 程序命名规则命名方法之所以要标准化，主要出于以下几个目的。1) 即使只从名字，也可以判断出起什麽作用？ 是何种类型？ 提高了可读性及可维护性；2) 避免编译及链接时的冲突/不一致，而这种冲突/不一致在把一些模块移到别的一些操作系统中时有可能发生；3) 阅读源程序以及进行调试时，某个符号属于哪一个模块，能很快的明白；4) 和用途直接有关的固有名词的使用， 能够防止由于疏忽而错误地使用于别的用途。对于变量来说，一个用途一个变量是一个重要的原则；5) 可维护性。命名的方法是随着软件系统开发使用的编程语言和编程工具的不同而变化的。 例如：编程语言的不同决定了可使用的字符，X-Windows编程时使用X-Windows形式的命名原则因此，详细的规定必须根据项目Project的不同情况而定。“开始编程之前，必须设定编程详细准则”是一个必须遵守的原则。以下，将阐述我们在设定详细准则时，一些必须考虑到的基本原则，并提供一些范例。标识符是程序中用来代表变量、标号、函数、窗口、菜单、控件和对象等名称的符号在源程序中使用的标识符（变量，函数，文件），应该满足下列基本条件：1、 必须以字母或下划线开头； 2、 其它可以是字母、数据及些特殊符号；3、 最长为40个字符，中间不能有空格；4、 保留字不能作为标识符；5、 根据其名称，可以容易地推断它的用途；6、 根据其名称，可以容易地推断变量的作用域和类型 1) 变量的命名及定义对于PB来说，它有五个系统预定义的全局的变量：SQLCA、SQLDA、SQLSA、Message、Error，这五个变量名在程序中不要显式定义，其它变量名的定义遵循如下规则：权限（A） + 类型缩写（B） + _ + 拼音缩写、英文（C）说明：（1）、定义的变量一律小写； （2）、权限（A）列表：权限缩写全局变量g共享变量s实例变量i局部变量l （3）、类型缩写（B）数据类型缩写BolbBbBooleanBChar 或 CharacterCDateDDateTimeDtDec 或 DecimalDcDoubleDbInteger 或 IntILongLRealRStringSTimeTmUnsignedInteger 或 Unsignedint 或 UintUiUnsignedLong 或 UlongUl （4）、拼音码缩写（C）:能表达此变量用途的中文拼音缩写 例如：统计数据窗口返回的总行数则可定义变量 Int li_zhs （5）、例子：Int li_zhs Long ll_hd 变量的定义遵循如下语法：数据类型精度 变量名数值 =初值，变量名数值 =初值.说明：（1）、数据类型采用首字母大写，其它小写； （2）、变量的命名以上面的规定为准。 变量的定义注意点： （1）、一个变量一个用途 一个变量，只使用在一个用途上，决不用于复数个用途上。无论是在开始编程阶段，还是在维护的阶段做功能追加及变更时，都应该遵守该原则。但是局部的循环记数变量属于例外。 （2）、一个文字的变量名 一个文字的变量名如 i,j等 尽可能不要使用。 尤其不能在全局变量中使用。如果使用了，当某个功能发生变更时，将导致和该变量有关部分要变更。要检索出使用了该变量的部分很困难。全局变量等重要的变量至少使用2文字以上的字符，这样使用编辑器可以无遗漏地方便地检索出。 （3）、给变量名一个正确的含义 使用正确的名字给变量命名，即变量名和用途相符合， 以免维护人员产生错误的理解。（能用英文单词修饰尽量用英文单词，否则用拼音码缩写）。 （4）、变量全部小写2) PB对象的命名部分PB对象前缀：结构 str用户对象 u菜单 m生成新的对象后必须在库中对象的属性中加入注解。（1）、函数： 应用系统级：f_拼音缩写、英文窗口级： wf_拼音缩写、英文用户对象级：uf_拼音缩写、英文菜单级： mf_拼音缩写、英文 （2）、结构：应用系统级：str_拼音缩写、英文窗口级： wstr_拼音缩写、英文用户对象级：ustr_拼音缩写、英文菜单级： mstr_拼音缩写、英文（3）、窗口： 功能代码 P业务处理 Q业务查询 C业务统计 S系统维护 w_功能代码_拼音缩写（4）、用户对象：uo_拼音缩写、英文（5）、管道： p_拼音缩写、英文（6）、查询： q_拼音缩写、英文（7）、数据窗口：功能代码 P业务处理 Q业务查询 C业务统计 S系统维护 d_拼音缩写 （8）、控件： 系统默认的XXX_ + 拼音缩写、英文2. 程序的书写规则1) 保留字、特殊字符系统所定义的98个保留字不能作为标识符，都必须大写。对于特殊字符必须用波浪号（）引用。2) 外部函数的声明外部函数是指使用其它语言（PB以外的语言）并保存在动态库中的函数。有两类外部函数要声明：（1）、全局的外部函数；（2）、局部的外部函数。从返回值的角度来看有两类函数：（1）、有返回值（即通常意义上的函数）；（2）、没有返回值（即通常的过程）。带返回值的外部函数的声明：(在应用中声明时必须写在一行上)ACCESS FUNCTION retype funname (REF datetype arg1,) LIBRARY “libname” ALIAS FOR “extname”带返回值的外部函数的声明：(在应用中声明时必须写在一行上)ACCESS SUBROUTINE retype funname (REF datetype arg1,) LIBRARY “libname” ALIAS FOR “extname”说明：（1）、ACCESS 在局部外部函数中指明访问的范围，有效值是PUBLIC、PRIVATE、PROCTECTED； （2）、FUNCTION、SUBROTINE是保留字必须大写； （3）、rettype外部函数的返回类型； （4）、funname 是动态库中定义的函数名称； （5）、REF 是传参方式； （6）、LIBRARY 保留字； （7）、ALIASFOR保留字，给外部函数加个别名；（8）、例子： FUNCTION Uint waveOutGetNumDevs() LIBRARY “WINMM.DLL”3) 操作符操作符代表符号化的运算，分为四类：算术操作符、关系操作符、逻辑操作符、连接操作符。由于操作符有优先级，所以在进行符号运算时一定要合理运用“（）”进行调度，以达到预期目的。4) 赋值语句赋值语句用于变量和对象属性的赋值，这是程序中使用最频繁的语句。语法格式： variablename = expression说明： variablename 是变量或对象属性 expression 是表达式，一定要注意类型的匹配、兼容，以及数据的四舍五入造成的数据误差。5) 直接数值使用的禁止在程序中直接使用数值的编程方法，绝对禁止使用。尽量使用定义或参数设定，其原因如下：l 在将来变更的时候，需要修改源文件，或者比较导致修改比较复杂，而容易产生漏改等错误。l 光从数值上来看的话，不容易明白其含义。对这种定数命名时，必须采用望其名通其意的名称来全局或局部的常量定义。在程序中使用该常量。例：CONSTANT Int gi_length = 256CONSTANT Strig ls_person = 0116) 脚本和函数的书写格式 （1）、注释无论函数也好，数据结构也好，必须有相应的注释。注释的目的，是为了将来软件维护的时候，即使不看源程序，只看注释的内容，也能够充分理解。注释主要记述以下几个方面的问题： 功能，设计说明，限制事项，边界条件，假定或潜在的问题。注释不是程序语句的改头换面，而是从更高的一个层次来阐述说明。注释在下述场所必须追加；1) 所有函数的开头2) 主要变量定义的后头3) 给表字段、数据窗口列赋值的代码后一定要注释字段的中文含义4) 事件、函数内部的变量，和参数的定义处5) 各个函数、事件中关键处理块的开头A、 在应用OPEN事件的开头，下述著作权表示的注释要写。/ Copyright ZhongYa(NANJING) COMMUNICATION CO. 1999/ All Rights Reserved 。Writed By Round-The-World Developer/ 开发工具: PowerBulider 、Ms-SqlServer 7.0/ 时 间: XXXX年XX月XX日/ 说 明: /对于一般的事件也可以加入如上的注释。/ 功能说明：/ 变更记录: 变更或版本更新的时候/ 日期 版本号 变更者名 变更内容/ 2000/01/01 1.0 MR.dess 开发/ 2000/02/05 2.0 Mr.chen 修改入口参数名称/B、 在函数的开头，加入如下格式：/ 函数名称: f_XXX / uf_XXX / mf_XXX / wf_XXX/ 目的用途: / 作用范围: PUBLIC / PRIVATE / PROCTECTED/ 输入参数: DataType ab_boolean/ 返回参数: DataType Y when ab_boolean is true/N when ab_boolean is false/ 变更记录: 变更或版本更新的时候/ 日期 版本号 变更者名 变更内容。/ 2000/01/01/ 1.0 MR.dess 由于版本更新，对函数返回类型/ 进行更改/ 2000/02/05 2.0 Mr.chen 修改入口参数名称/ C、变量及参数的注释对于一些主要的变量、数据结构定义，要说明它是什麽样用途的定义，以及如何被使用的。例： Int li_id;/* Process ID*/String ls_jobid /* Job ID*/ D、关键处理块的注释对于关键处理块的说明，要从详细的设计层次来阐述。而不是简单的程序语言的改头换面，那样只能使注释单调烦琐。 E、给表字段、数据窗口列赋值的代码后一定要注释字段的中文含义ids_cfje.SetItem(ll_insertrow,cfh,as_cfh) /处方号ids_cfje.SetItem(ll_insertrow,cflb,ls_tsfl) /处方类别(普通、毒麻处方)ids_cfje.SetItem(ll_insertrow,je,ldc_sl * ldc_lsj) /金额ids_cfje.SetItem(ll_insertrow,jelb,ls_jelb) /金额类别ids_cfje.SetItem(ll_insertrow,ts,ll_ts) /帖数(草药处方)ids_cfje.SetItem(ll_insertrow,fyzd,gs_zdh) /发药站点（2）、数据类型、PB函数名称的书写严格按PowerBuilder 系统的写法，基本是具有独立的意义的词或单词首字母大写，其它小写，例如：MessageBox(),SetPointer(Arrow!)（3）、续行通常情况下，PowerScript 的一条语句书写在一行。语句书写完毕后，按ENTER键转到下一行，开始下一条语句，有时，为了阅读的方便，需要把一条语句写在多行上，采用续行符“&”，例如：Messagebox (用户对象外部函数,初始化用户对象外部函数发生一个错误rn +& 在这个应用中将无法无正确进行外部调用”)（4）、缩进格式程序必须采用缩进格式。（5）、控件的继承系统中所用的控件全部从公用库中继承，若公用库中没有所需的控件时请通知有关负责人在核心库或公用库中进行增加，不能自行处理。控件中的文字一律以公用库中的命名为准，不能私自改动，不得以时要求通知有关负责人进行处理。3. 部分编码、标志的规则说明对于数据库中BM 或具有BM含义的字段一律以“编码”为中文名，对于数据库中的BZ或具有BZ含义的字段一律以“标志”为中文名。对于可枚举的变量一律以数据库中定义的枚举值和编码为准，不得私自设定。4. 代码的变更软件进行修改的时候，修改的原因和改动说明，为了让别人能够明白，必须加以一定的注释。而这种做法的目的有以下的重要意义：1) 错误问题发生的时候，可以帮助快速定位问题的发生点。2) 对于软件的版本更新管理有重要的意义。对于变更的地方，必须追加满足下述条件的注释。1) 注释要覆盖变更部分的整体范围。因此，对于每个变更部分的开始和结束，都要追加以下的注释。/* Zhang 于2000.02.19 因 xxxxxxxxxxxxxxx作修改/删除/增加 */ ./* 修改/删除/增加结束 */此种注释，最好对于比较大程度范围的变更比较有效。 在有很多细微的变更的地方，可以采用以下注释方式。/* Zhang 于2000.02.19 修改 gb_Status = FALSE */gb_Status = TRUE或者/* Zhang 于 2000.02.19 因有bug lack 作了修改 */ li_count = dw_person.OBJECT.countli_row;/* li_count = dw_detail.OBJECT.countli_rows; */2) 变更的时间以及版本号要记录在版本发行以前如果作变更，不需要加入版本号。3) 变更部分的注释格式要统一这样可以使用编辑工具或者检索工具，把所有的变更没有遗漏地检出。所以使用一定的关键词是有必要的。4) 变更的位置，要一目了然要求注释的格式是醒目并且整齐。5) 变更方法由于变更后经常要参照变更前的源程序，考虑到这种情况，可从下述的三种变更方法中选择一个最合适的，在项目中判断。 A、源程序必须留下。利用条件编译能清楚的看见变更前后的源程序，且可以简单地进行变更前后的切换。/* Zhang 于 2000.02.19 因有bug lack 作了修改 */*变更前的源程序xxxxxxxxxxxxxxxxxxxxx;xxxxxxxxxxxxxxxxxxxxx;xxxxxxxxxxxxxxxxxxxxx;*/修改开始变更后的源程序xxxxxxxxxxxxxxxxxxxxx;xxxxxxxxxxxxxxxxxxxxx;xxxxxxxxxxxxxxxxxxxxx; /修改结束B、利用版本管理。对于需要变更的源程序，直接给予变更。然后利用版本管理工具来管理各个阶段版本的源程序。或者只是简单地把原有的程序拷贝到另一个目录中，在必要的时候，在进行文本文件的对比，以明确其差异。但也存在一个问题，即不容易知道是否是新还是旧版本。5. 附录 例程序1、函数范例：/ 函数名称: f_profile_s