domino开发规范V2.doc

MDCL Domino开发规范严格保密，仅用于MDCL Domino开发工作MDCL Domino R5开发规范版本号:2.0作者：MDCL石振勇2003年7月2日目录1.表单规则:411 表单命名规则412 表单的Js Header413 表单的On KeyDown事件414 表单的OnLoad415 表单的内置HTML516 表单上通用的后台控制信息517 后台控制域的组织52域的规则621 域的命名规则63视图的规则631 视图的命名规则632 视图的索引733 视图的列734 视图的选择公式735 嵌入视图74代理的规则841代理的命名规则842 代理的其他规则843 同时运行代理844防止资源冲突85Script库的规则951 Script库的命名规则952 Script库的内容96LotusScript代码规则961 函数的长度962 函数的命名963参数的规则1064 函数的返回值1065 函数的职责1066 变量的规则1167 其他规则117公式规则128执行效率1281逻辑短路问题1282惰性初始化问题149注释规则1591 函数体注释1592 代码行注释1510调试日志15101问题15102解决办法16103结论1711错误处理17111捕捉代码执行的错误17112主动触发错误1812 其他18121参考资料18122 网上资源18Modern Devices (China) Ltd. 第18页 2020-1-111.表单规则:11 表单命名规则l 表单名称统一用中文,尽量能展示该表单的功能和意图.l 如果表单名无法展示其意图,或者表单名必须用英文,或者需要对表单做些其他说明,则填写表单的备注.l 必须填写表单的别名.别名的可以用英文单词组合或汉语拼音.如果用拼音,在能够容忍的长度内,尽量用全拼。规定：如果名称全拼在16个字之内，用全拼并且每个字的首字母要大写。如果超过16个字，则全用每个字的首字母大写。l 表单名无需加”fm”的前缀。但可以按其功能类别加前缀，比如用于区分“核心表单和非核心表单”的前缀l 对于不需要用来创建文档的表单，名字用括弧括起来，用以将后台表单和前台表单区分开，如功能性的表单作为后台表单。12 表单的Js Header三个层次：l 具有通用性的，可以提取的js函数独立到一个单独的资源数据库中。l 本数据库内具有通用性的js函数可以打包放到本数据库的名为“JsHeader”的页面里。l 表单的Js Header中的函数应尽可能的少。只保留仅与本表单相关的特殊的Js函数。规定：放在页面里的js函数包要在页面中写明每个包中的函数名称，方便查找和查看。 资源库中的js函数包同时要有同名的说明文件。还要求有一个总体说明文件。13 表单的On KeyDown事件可以在此函数中限制用户的一些按键，例如：/防止用户CTRL+N,避免繁盛保存冲突if(event.keyCode=78&event.ctrlKey)return false;14 表单的OnLoadOnload中的代码要尽可能的简短，不要写具体的实现代码，只写被调用的函数体即可，目的是为了代码清晰简洁，便于维护。例如：/打开前设置相关状态域ondocload();/装载意见LoadOpinion();/修改附件链接ModifyAttachLink();/上载附件AddAttach();15 表单的内置HTML表单的内置HTML的颜色应设置成蓝色（RGB：0，0，255），字体为宋体，字号为9号，以便于与表单上其他普通文本的区分。16 表单上通用的后台控制信息表单的一些后台控制域，后台控制的HTML等，如果是通用的，要独立成相应的子表单。按其性质放置到不同的子表单上。要达到这样的效果：其他程序员不用去遍历每个域，只看几个子表单的名称，就能猜测出某个域在哪个子表单下。并且表单的开头写上该表单的名字的文本。17 后台控制域的组织171一般后台控制域应该组织到两列多行的表格中，每一行的第一列写明该域的注释和该域的实际的名字，字体用宋体，字号用9号，颜色用红色；第二列放置该域字体用宋体，字号用9号，颜色用黑色。172还有一种特殊情况：一组域都是多值域，并且这组域的每个值是一一对应的。例如以下三个域：“环节名称” “环节处理人” “环节开始时间”。这种情况应该这样组织：“环节名称”域的注释“环节处理人”域的注释“环节开始时间”域的注释“环节名称” 域“环节处理人” 域“环节开始时间”域 并且每个域的“显示数据时的分隔符”属性设置为“新行”，设置后所产生的文档在notes中显示效果如下，便于查看数据：NO环节开始时间UPUkssj环节结束时间UPUjssj01234567省公司综合部|李琦/SGS/SDMCC省公司综合部|王敬国/SGS/SDMCC省公司财务部|于志明/SGS/SDMCC省公司人力资源部|王山湖/SGS/SDMCC省公司市场部|陈和平/SGS/SDMCC省公司网络部|李锋/SGS/SDMCC省公司综合部核稿|卢雪丽/SGS/SDMCC省公司综合部|王敬国/SGS/SDMCC2002-10-22 13:42:542002-10-22 13:45:012002-10-22 13:46:432002-10-22 13:46:432002-10-22 13:46:432002-10-22 13:46:432002-10-22 14:12:032002-10-22 14:15:042002-10-22 13:45:012002-10-22 13:46:432002-10-22 14:12:032002-10-22 14:13:422002-10-22 14:15:04*2域的规则21 域的命名规则l 可以用英文单词组合或汉语拼音.如果用拼音,在能够容忍的长度内,尽量用全拼。规定：首字母大写用全拼。l 域名不要加用以说明域的类型属性的前缀。但可以按其功能类别加前缀，比如用于区分“核心视图和非核心视图”的前缀l 域名可以加其功能类型的前缀，用于功能类型有限时。当功能类型几十上百种时，就没意义了。3视图的规则31 视图的命名规则l 视图名称统一用中文,尽量能展示该视图的功能和意图.l 如果视图名无法展示其意图,或者视图名必须用英文,或者需要对视图做些其他说明,则填写视图的备注。规定：如果视图本身是被调用的在备注中必须写明被谁调用。l 必须填写视图的别名.别名的可以用英文单词组合或汉语拼音.如果用拼音,在能够容忍的长度内,尽量用全拼. 规定：如果名称全拼在16个字之内，用全拼并且每个字的首字母要大写。如果超过16个字，则全用每个字的首字母大写。l 视图名无需加”vw”的前缀.l 对于不需要用于前台显示的视图，名字用括弧括起来成为隐藏视图，用以将后台视图和前台视图区分开32 视图的索引“刷新索引”属性一般选为：“自动刷新”“废弃索引”属性一般选为：“不废弃”对于“用户经常访问，视图中文档经常变动”的视图，这种设置有助于提高视图的打开速度33 视图的列l 一般应填写列的“标题”属性，用于辨别该列l 视图的列的内容的字体应统一设置，一般字号设置为9，字体为宋体，颜色根据客户需要设置，风格应协调统一。l 视图的列公式尽可能的简洁，减少计算量。l 避免使用时间相关的列公式， 比如Now, Created, Modified.l 列尽可能不排序l 删除所有不必要的列34 视图的选择公式l 避免使用复杂的视图选择公式l 视图选择公式避免使用与时间、当前用户相关的函数或命令35 嵌入视图视图作为“嵌入元素”嵌入页面或表单时，“要显示的行”属性的数字尽量设置的少些，以提高嵌入视图的打开速度。规定：初始值设为20行，如果用户提出速度问题，可以改为10行，作为第一解决方案。4代理的规则41代理的命名规则l 代理的名字可以用英文单词组合或汉语拼音.如果用拼音,在能够容忍的长度内,尽量用全拼. 规定：如果名称全拼在16个字之内，用全拼并且每个字的首字母要大写。如果超过16个字，则全用每个字的首字母大写。l 必须填写代理的备注，对代理进行详细的说明。l 代理名加用于标明其是否为核心代理的前缀.42 代理的其他规则l 对于定时执行的代理，在该数据库正式启用前，或者该定时代理暂时不使用，取消代理前的复选框，以暂时禁用该代理。l 对于那些只为管理者在客户端使用的代理，应设为“私有代理”l 代理 “Sub Initialize” 中的代码要尽可能的简短。多个代理中或和其他设计元素中共享的代码，应独立到“script库” 中。43 同时运行代理缺省的，domino同一时刻只执行一个web代理（串行）， 配置domino并行运行web代理能够提高应用的答复时间。配置并行运行代理，需要设置服务器文档中HTTP页下的“是否同时运行web代理”或者在notes.ini中设置这一行“DominoAsynchronizeAgents=1” 44防止资源冲突同时运行web代理时，为防止资源冲突，要使用用加锁机制，例如:SharesResources = docCgi.UNID(0) + savelockID = Createlock(SharesResources)gotLock = Codelock(lockID)=/你的代码=If (gotLock) ThenreleaseLock = Codeunlock(lockID)dseleteLock=Destroylock(lockID)End If5Script库的规则51 Script库的命名规则l 目前命名方式参照了java类文件的命名方式，即公司internet域名的倒写。l 命名可以反映多个script库之间的关系，比如“com.mdcl.util.UrlParameter”和“com.mdcl.util”虽然从代码上两个库没关系，但是从功能上说明“com.mdcl.util.UrlParameter”也是一个通用的工具类，属于“com.mdcl.util” 52 Script库的内容l script库中要放功能相近的代码，以达到“高内聚”的目的。也便于查看代码。l Script 库的开头区域要有对整个Script说明的注释。6LotusScript代码规则61 函数的长度函数中的代码行数不要多于50行。这是一个最重要的规则。62 函数的命名让我们看一些错误的命名：PersonLog 更新人员日志PeopleOut 打印人员外出的信息RemoveUser从文档的当前环节和当前处理人中删除指定处理人RenyuanJB计算人员的级别相对比较正确的应该是这样UpdatePersonLog 更新人员日志PrintPeopleOut 打印人员外出的信息RemoveUserFromDoc从文档的当前环节和当前处理人中删除指定处理人GetPersonLevel 计算人员的级别621 函数的名字用英文单词组合。 622 函数名字的语法结构,一般应采用“动宾”等动词开头的结构623 函数的名字在能容忍的程度内，尽可能的长，以更好的揭示意图624 函数的名字应和函数的功能一致，不可超出或小于函数的功能，或者“风马牛不相及”。63参数的规则6.3.1参数名字要有意义例如：sub SetValue(width, height) 良好的风格sub SetValue(x,y)不好的风格例如编写字符串拷贝函数StringCopy，它有两个参数。如果把参数名字起为str1和str2，例如function StringCopy( str1, str2) 那么我们很难搞清楚究竟是把str1拷贝到str2中，还是刚好倒过来。可以把参数名字起得更有意义，如叫strSource和strDestination。这样从名字上就可以看出应该把strSource拷贝到strDestination。632如果输入参数以值传递的方式传递 ，则宜改用“ByVal argument”方式来传递，这样可以防止作为参数的变量值被修改，同时又可以省去临时变量的构造过程，从而提高效率。633 避免函数有太多的参数，参数个数尽量控制在5个以内。64 函数的返回值l 要书写函数的返回值类型l 函数的返回值要与函数的名字相配合l 函数的正常返回值和错误返回值的区分l 函数尽量不要通过参数传递函数的返回值65 函数的职责函数的职责要单一，如果觉得职责的“粒度”不好把握，可以先用自然语言写出总控模块（可以作为注释），针对自然语言的每句话即可作为一个函数。 66 变量的规则l 变量的定义后面要书写该变量的注释l 变量的作用范围尽量少用全局，作用范围越小越好l 变量尽量都要定义类型l 少使用Variant类型l 一组变量作用相近时，可将这组变量集中在一起定义，并且对该组变量作个说明，比如下面分为两组 me对应的实体 Private mAppDoc As notesdocument 应用主文档Private mAppDB As notesdatabase 应用数据库Private mCurUser As FlowUser 当前使用人Private mAppDocCurNode As node 应用文档当前环节以应用数据库为中心的周围各种引擎、资源、工具的实体Private mOAfactory As OAfactoryPrivate mFlowConfig As FlowConfig 本应用对应的流程配置库Private mOrganization As Organization 本应用对应的人员组织库Private mFlowSession As FlowSession 本应用对应的SessionDoc,用于会话级共享数据Private mFileInterface As FileInterface 处理本应用文档的界面Private mWorkFlow As WorkFlow 后台状态Private mOutOffice As OutOffice 人员外出Private mUtil As Util 处理主要类型变量的工具集67 其他规则l 使用For循环代替Do循环l 遍历数组元素时，使用Forall代替Forl 避免使用不必要的数组，例如：片断A比片断B快一倍。 片断 Afor i=1 to 100sum = sum + x(i)nextt(1)=sum片断 Bfor i=1 to 100t(1)=t(1)+x(i)Nextl 将Redim的使用降到最少l 使用GetNextDocument代替GetNthDocument 7公式规则l 尽可能不用或少用DbColumn,DbCommand, DbLookupl 尽可能使用视图列序号而不是域的名字作为DbColumn or DbLookup的参数l 使用DbColumn,DbCommand, DbLookup.时，尽量开启“缓存”参数8执行效率81逻辑短路问题逻辑短路指的是有的编程语言执行类似下面的语句时，if func1 and func2 and func3 thenend if当发现func1为false时就不会继续判断func2和func3，直接返回结果。但是lotus Script 不具备这种功能，即使func1返回false，它依然判断func2和func3。针对这种情况，我们的lotusScript 应写成这样：if func1 thenIf func2 thenif func3 thenend ifend ifend if这里面三个if还有个排序问题，返回值最有可能为false的排在最前面，然后按照其可能性递减往后排。以上的问题都建立在一个假设之上，即所判断的“func1、func2、func3”不是简单的变量，而是一个复杂的函数。这样的话才有意义，否则判断一两个变量花不了多少时间，没必要这样费脑筋。以上的判断表达式是“逻辑与”，针对“逻辑或”表达式存在同样的问题。If func1 or func2 or func3 thenEnd if改为If func1 thenelseif func2 thenelseif func3 thenEnd if这里面三个if也有个排序问题，返回值最有可能为True的排在最前面,然后按照其可能性递减往后排。不仅仅是单个if语句需要考虑这个问题。可以看下面的函数，当一个函数需要比较好多条件，并且多个条件并或关系不固定时，需要考虑如何节省判断时间。总结起来的规则就是“子条件之间并关系时，当前子条件成立才继续比较后续子条件 ；子条件之间或关系时，当前子条件不成立才继续比较后续子条件” NAME ifUserCanCreateFile(docFileType,CurUser ) PARAMETERS docFileType,文件类型文档 CurUser ,给定的用户 PRE-CONDITIONS RETURNED VALUES 路径是否有效，布尔值 LAST UPDATED BY Zyshi LAST UPDATED DATE 2002-6-4,2002-8-19 VERSION NUMBER 2.0 DESCRIPTION 判断给定用户能否创建给定类型的文件Function ifUserCanCreateFile(docFileType,CurUser )If docFileType.WJacl(0)=0 Then 权限类型：直接提供此路径给用户选择|0Flag_valid=TrueElseif docFileType.WJacl(0)=2 Then 权限类型：暂时封闭此路径|2Flag_valid=FalseElseif docFileType.WJacl(0)=1 Then权限类型：根据条件设置提供此路径给用户选择|1If docFileType.WJorgCondlogic(0)=and Then计算几个小条件之间的并或关系isSubAnd=TrueElse isSubAnd=FalseEnd IfIf docFileType.WJorgLevel(0) = 1 Then 人员组织级别作了限制Flag_valid=CompareLevel(CurUser.level,docFileType.WJhxzz)是否符合组织级别限定If Not (isSubAnd Eqv Flag_Valid) Then子条件之间并关系时，本子条件成立才继续比较后续子条件 子条件之间或关系时，本子条件不成立才继续比较后续子条件ifUserCanCreateFile=Flag_ValidExit FunctionEnd IfEnd IfIf docFileType.WJorggroup(0)=1 Then 工作岗位做了限定，并且需要继续比较时Flag_Valid=mUtil.isIntersection(docFileType.WJhxGW,CurUser.Group) 是否符合岗位限定If Not (isSubAnd Eqv Flag_Valid) Then子条件之间并关系时，本子条件成立才继续比较后续子条件 子条件之间或关系时，本子条件不成立才继续比较后续子条件ifUserCanCreateFile=Flag_ValidExit FunctionEnd IfEnd IfIf docFileType.WJorgdept(0)=1 Then 部门做了限定， 并且需要继续比较时If mUtil.FindPositionInArray (docFileType.WJhxbm,CurUser.Dept) =-1 Then 是否符合部门限定Flag_valid=FalseElseFlag_valid=TrueEnd IfIf Not (isSubAnd Eqv Flag_Valid) Then子条件之间并关系时，本子条件成立才继续比较后续子条件 子条件之间或关系时，本子条件不成立才继续比较后续子条件ifUserCanCreateFile=Flag_ValidExit FunctionEnd IfEnd IfEnd IfifUserCanCreateFile=Flag_ValidExit Functioner:Call mError.TreatWithError(Func ifUserCanCreateFile,Class FlowConfig)End Function82惰性初始化问题 只在需要的时候实例化一个类，或对一个变量赋值，而不是在程序的开始就作。9注释规则91 函数体注释针对每个函数，按照下面的模板进行注释 NAME 名字 PARAMETERS 每个参数的名字、意图、类型 PRE-CONDITIONS 前提条件RETURNED VALUES 类型，格式 LAST UPDATED BY 作者 LAST UPDATED DATE 2002-1-28,2002-3-11 VERSION NUMBER 2.1 DESCRIPTION 实例化本类sub subNamedim .setend sub92 代码行注释对于变量、关键的代码行都要在其右边进行注释。10调试日志101问题程序调试时往往需要在日志上打印一些运行中变量的值，如果简单的写msgbox 就会带来很多问题，通常程序发布后没有及时清除msgbox，使发布后的程序“不干净”102解决办法有两种办法：1021过全局变量开关来决定是否msgbox代码示例如下：在定义全局变量的地方dim debug as integer 有两种值 1代表调试版本，0代表生产版本debug=1在需要打印变量的地方if debug=1 thenmsgbox “变量名”+变量值end if1022通过一个debug类来处理代码示例如下：在定义全局变量的地方dim mDebug as new Debug 有两种值 1代表调试版本，0代表生产版本在需要打印变量的地方call mDebug.msgbox (“变量名”+变量值)调试阶段的Debug类的msgbox方法如下public sub msgbox(debugInfo)msgbox debugInfoend sub生产阶段的Debug类的msgbox方法如下public sub msgbox(debugInfo)msgbox debugInfoend sub1023以上两种方法的比较项目优点缺点通过全局变量开关来决定是否msgbox1 不必实例化一个类，系统开销小；2 不必调用一个自定义类的方法，运行速度快。1 程序发布后，要在每个模块中调整全局变量开关。2 程序员每次要打印调试信息都要作判断，较为麻烦3 当打印的变量较多时，程序要作过多的判断，降低运行速度。s通过一个debug类来处理1 程序发布后,只需修改debug类的msgbox方法即可2 程序员打印变量值方便，只需要mDebug.msgbox即可1必须要实例化debug类，系统开销增大；2程序员打印变量值，需要调用”debug”这个自定义类的方法，当打印的变量特别多时，s降低运行速度。103结论规定：统一采取debug类方式进行msgbox提示。msgbox的三级管理：l 程序正在调试中，可以适当添加任何msgbox提示，但是一旦程序交付使用，必须删除所有临时性提示。l 对于比较重要的需要长期反复观测的变量的msgbox提示，必须遵循如下规则打印：mDebug.msgbox（ “Sub ini,Agent CreatDocument”+”变量名”+变量值+编程者自己的名字汉语拼音缩写）其中Sub ini,Agent CreatDocument可以直接从error的参数中拷贝。l 最终稳定运行后可以统一用类注释的方式将所有提示关掉。11错误处理11