专业文档流程编写规范doc.docx

1、专业文档流程编写规范docIVR 流程编写规范IVR Coding Standard编制单位：新太科技技术开发中心编制时间：2004/2/20文档编号：SPMS-SEP-12版 本 号：内部试用版编制审核批准生效日期汤冬儿赵刚张少文2004.2.25变更记录A - ADDED M - MODIFIED D - DELETED序号日期章节号A/M/D变更简述变更人1. 目的 本部分编写规范适用于新太IPS流程编写。2. 说明本规范作为一个标准的IPS流程编写规范，其中对于规则是必须遵守的，建议是提醒您需要注意的地方，或者是在该情况下一个较好的选择。3. 流程规范3.1 组织结构规则1-1：在流程

2、文件存放的根目录下，只能有 .sc、.cod 、.ini文件。其他的文件，按所属业务不同存放在不同的目录下，保持流程的根目录清洁。建议1-1：不同类型文件按类型分目录存放，原则是要类型分明，便于管理，便于过期删除，目录下文件如果有无限增长的趋势，请按一定规则（例如日期）分目录存放。建议1-2：放音动作所需的语音文件.vox /.v41文件，在 ./vox/ 目录存放；流程图等文档说明在 ./doc/ 目录下存放。3.2 排版规则2-1：流程中各状态块间保留1行空行。规则2-2：函数之间保留3行空行。规则2-3：流程头部配置参数、宏、函数、全局变量定义区域按先后顺序分开并注释含义，便于查找。例1

3、：/*/流程配置参数定义/*#iniparam string sAgentStartTime /座席开始服务时间#iniparam string sAgentStopTime /座席结束服务时间#iniparam string sCurrencyFaxFile /货币代码传真文件#iniparam int nMaxTalkRecs /系统最大的可说资源数/*End of 配置文件*/*/流程宏定义/*#define INPUTERRLIMIT 3 /输入错误次数限制#define ACCOUTLENGTH 23 /账号长度（最长）#define MAINPATH .sysvox /主函数语音文

4、件根目录#define MAINVOX1 NQQWel.vox /您好，QQ现已开通千里音缘服务#define MAINVOX2 NQQCity.vox /千里音缘目前已开放四川、海南两地/*End of 宏定义*/*/流程函数定义/*#function main /主函数#function OnClear_QQCallOut /异常处理函数/*End of 函数定义*/*/流程全局变量定义/*#declare SR g_sAstring = This is a string /一个全局使用的数据串#declare FR g_fMyMoney = 10.5 /一个全局使用浮点数，表示金额#de

5、clare IR g_nCount /整型全局变量表示数目/*End of 全局变量*规则2-4：使用不同编辑工具时，要求定义Tab键为4个空格位（不要用空格填充）。规则2-5：函数体里状态左缩进一个Tab键，保持左对齐，该状态下的动作、事件语句左缩进一个Tab键，保持左对齐。规则2-6：流程动作语句中，“”符号右边保留一个空格；“”符号左边保留一个空格；流程动作中参数分隔符“,”右边保留一个空格。规则2-7：流程动作语句中，状态跳转符号“-”之前至少要保留一个TAB键（最好同一个状态下的所有-符号都对齐），“-”之后要保留一个空格。例2：:stNationalQQCallIn /外省用户呼入

6、 Strsub $CallerID, 1, 2 Equal SR0, 13 Passed - stLocalQQNormal /本地用户Failed - stNationalQQCall /外地用户规则2-8：iniparam，define，declare等定义时，第二个参数和第三个参数之间用一个或者多个Tab键间隔开，以对齐美观为准。示例参见上面例1。3.3 注释规则3-1：一般情况下，源程序有效注释量必须在20%以上。说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。规则3-2：流程头部配置参数、宏、函数、全局变量定义区域按

7、先后顺序分开并注释含义。示例参见上面例1。规则3-3：流程头部必须注明各种配置参数使用约定。规则3-4：在流程头部定义全局变量的同时须明确列出该全局变量的含义及使用方案。例3：/* 全局变量 *#declare IR g_nLeaveWordType = 0 /留言类型 0发送留言，1转发留言，2回复留言#declare IR g_nCanChoose = 1 /收听用户资料时是否可以按键选择#declare SR g_sYWBegintime = /当前业务开始时间 字符串yyyy-mm-dd hh:mm:ss/* End of 全局变量 *规则3-5：流程头部必须有自定义函数功能介绍。规则

8、3-6：函数体开始之前必须有传入、传出参数解释，函数返回值解释。返回值的一般0表示正常，1表示有错，9表示异常退出，4表示转座席、8回主流程、7回上级菜单。例4：/*/Function name: FormatTxtFile/Function usage: 用于将文本文件转换成传真文件/传入参数：/g_sTxtFileName: 需要转换的文本文件；/传出参数：/g_sFaxFileName: 转换后的传真文件名；/Returned: 0转换成功；9异常错误；/厦门建行客服中心/编写日期：03/22/2001/*规则3-7：子函数必须有编写/修改日期。示例参见例4。规则3-8：如果有与网关交易

9、部分必须明确收发包格式。例5：/*/function name:funcTrans282600/function usage:对公业务修改电话银行密码/传入参数：/传出参数：/Returned:0修改成功;9连接数据库失败/上传报文：|282600|9999|帐号|密码|/下传报文：|282600|返回码|/*规则3-9：注释应与其描述的代码相近，对子函数代码的注释应放在其上方，需与其上面的代码用空行隔开；对函数中代码的注释应置于右方相邻位置，不可放在下面。规则3-10：流程文件中尽量使代码右方注释处于同一列，方便阅读理解。规则3-11：流程中重要部分一定要注释。例如菜单选择后状态跳转。规则3

10、-12：涉及数据库操作必须注明实际SQL。 说明：明确数据库操作目的，方便后期调试、测试核对流程。例6：/* 查询不得注册用户黑名单（如电话卡用户）*/function name: funcQueryRegBlacklist/function usage: 查询主叫号码是否在不得注册用户黑名单（如电话卡用户）/传入参数：主叫号码$CallerID/传出参数：无/Returned：0表示非黑名单用户 1为黑名单用户 2为数据库超时/*funcQueryRegBlackList#declare IR m_nReturn = 0 /返回值 :stWait Assign g_sSQL, select

11、* from qq_RegBlacklist where F_caller like StrCat g_sSQL, $CallerID StrCat g_sSQL, % ExecSQL g_sSQL /select * from qq_RegBlacklist/ where F_caller like % Passed - stIsBlacklist Failed - stNotBlackList TimeOut - stTimeout:stIsBlacklist Assign m_nReturn, 1 /1表示是黑名单用户 ClearDTMF SetDTMF ? Assign SR0, MA

12、INPATH Strcat SR0, MAINVOX29 PlayFile SR0 /“本用户不能进行注册” StopPlayBack - stExit DialTerminate - stExit Failed - stExit:stNotBlackList Assign m_nReturn, 0 /0表示非黑名单用户 - stExit:stTimeout Assign m_nReturn, 2 /2表示数据库超时 - stExit:stExit Return m_nReturn /* End of 查询不得注册用户黑名单 *规则3-13：播放语音必须注释放音实际文字。便于核对流程，以及方便

13、阅读，以及语音文件遗失情况下恢复例7： :stBegin ClearDTMF SetDTMF 12 Assign SR0, INCARDPATH Strcat SR0, REGINPUTVOX1 /请输入您的个人资料，男生按1, 女生按2 PlayFile SR0 StopPlayBack - stSelectSex /选择性别 DialTerminate - stSelectSex Failed - stSelectSex规则3-14：在流程中使用到全局变量必须注释用途含义，保持全局变量含义统一，避免在另外一处改变其含义。例8： :stPromptUserType1 Assign g_nUs

14、erType, 1 /用户权限 为1级管理员 ClearDTMF SetDTMF ? Assign SR1, PROMPTUSERTYPEPATH Strcat SR1, PROMPTUSERTYPE1 /您好,您是本聊天室的1级管理员 PlayFile SR1 StopPlayBack - stExit0 DialTerminate - stExit0 Failed - stExit0规则3-15：边写代码边注释，修改代码同时修改相应注释，以保证注释与代码一致性。没用的注释要及时删除。规则3-16：注释内容要清楚、明了，含义准确，防止二义性。规则3-17：避免在注释中使用缩写，特别是非常用缩

15、写 说明：在使用缩写时或之前，应对缩写进行必要说明。建议3-1：通过对函数或状态、变量等正确命名，使流程代码成为自注释的。3.4 命名规则4-1：状态、变量、函数命名只能使用英文字母、下划线以及数字的组合。应当尽量使用常规的英文或英文缩写，避免使用无法阅读理解的命名方式。规则4-2：配置文件参数，如果是字符串string类型的以“s”做为前缀；如果是整数int类型的则以“n”做为前缀。例9：#iniparam int nMaxTalkRecs /系统最大的可说资源数#iniparam string sCurrencyFaxFile /货币代码传真文件规则4-3：宏定义必须全部大写。示例参见上面

16、例1中的宏定义。规则4-4：全局变量命名参见规则5-1“全局变量命名”。规则4-5：局部变量命名参见规则5-2“局部变量命名”。规则4-6：状态命名参见规则6-1“状态命名约定”。规则4-7：函数命名参见规则7-2“主函数命名”、规则7-4、规则7-5“自定义子函数命名”、规则7-6“自定义例外处理函数命名”。规则4-8：命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写。说明：较短的单词可通过去掉元音形成缩写，较长的单词可取单词的头几个字母形成缩写，单词的第一个字母大写。一些单词有大家公认的缩写。例10：如下单词的缩写能够被大家基本认可。Send 可缩写为 Snd;Re

17、ceive 可缩写为 Rcvtemp 可缩写为 Tmp;flag 可缩写为 Flg;statistic 可缩写为 Stat;status 可缩写为 Sta;message 可缩写为 Msg;规则4-9：命名中若使用特殊约定或缩写，则要有注释说明。规则4-10：用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。例11：begin/end create/destroy insert/delete put/get min/max 等。3.5 变量规则5-1：全局变量命名要以g_开头（g表示global），如果是字符串类型的则为g_s做前缀，如果是整型的则以g_n做前缀，如果是浮点型的则以g_

18、f做前缀。例12：#declare SR g_sAstring = This is a string#declare FR g_fMyMoney = 10.5#declare IR g_nCount规则5-2：局部变量命名要以m_为前缀（m表示member），如果SR类型的则为m_s做前缀，如果是IR类型的则以m_n做前缀。例13：#declare SR m_sAstring = This is a string#declare FR m_fMyMoney = 10.5#declare IR m_nCount规则5-3：全局变量定义区域参见规则2-3“流程头部配置参数、宏、函数、全局变量定义区

19、域”，示例参见例1。规则5-4：参见规则3-4“在流程头部定义全局变量的同时须明确列出该全局变量的含义及使用方案”。规则5-5：变量命名尽量符合该变量实际含义。规则5-6：去掉没有必要的全局变量，函数内部尽量使用局部变量。说明：全局变量是增大模块间耦合的原因之一，故应减少没必要的全局变量以降低耦合度。规则5-7：在流程开头仔细定义并明确全局变量的含义、作用、取值范围及全局变量间的关系。规则5-8：当向全局变量传递数据时，要十分小心，防止赋予不合理的值或越界等现象说明：当向全局变量传递数据时，应进行合法性检查，并在该行对变量含义做注释说明。规则5-9：寄存器变量使用一般作为IVR系统函数传递参数

20、/返回值使用。流程内部自定义函数不推荐使用寄存器变量。除了动作返回值等不得不使用寄存器变量的情况外，一律不使用寄存器变量，用自定义变量代替。规则5-10：参见规则3-14 “在流程中使用到全局变量必须注释用途含义，保持全局变量含义统一，避免在另外一处改变其含义”。规则5-11：防止局部变量与全局变量同名。规则5-12：严禁使用未经初始化的变量作为赋值。建议5-1：建议不使用IR0或者SR0作为后续状态的变量，特别的，如果要超过3个状态后仍然需要使用当前IR0或SR0的值，先把IR0或SR0赋值给其他变量中保存。3.6 状态规则6-1：状态命名约定以“st”开头，第三个字母大写表示实际有含义的名

21、称开始。例14：:stWaitConnect - stGetTime:stGetTime NowTime Assign m_sTime, SR0 规则6-2：函数中以状态stWait开始，以状态stExit结束。示例参见下面例15、例17。规则6-3：状态跳转为事件所驱动。3.7 函数规则7-1：在一个业务流程程序里面只能有一个主函数。 规则7-2：主函数只能名为main，在开始一个业务流程的时候自动执行。规则7-3：在一个业务流程程序里面可以有多个子函数。规则7-4：子函数名不能为main。规则7-5：自定义子函数除例外处理函数外，命名要以“func”开头，第五个字母大写表示实际有含义的名称

22、开始，尽量表示该函数执行的具体功能、操作。例15：/* 通用聊天过程 */function name：funcChatProcess/function usage：通用聊天过程/ 输入参数：g_nChatID 聊天室编号, g_nChatType 加入聊天的方式, g_nQQIdentify 加入聊天身份, / g_nTalkTime 聊天时长, g_nIsFullExit 当没可说资源时是否退出来,在主题聊天时会用到要退出/ 输出参数：无/ 返回值 0 正常退出, 1 对碰中退出, 2 聊天室编号不存在, 3 其他错误, 4 没可说资源的退出/*/通用聊天过程/*funcChatProces

23、s:stWait/action here.:stExit/* End of 通用聊天过程 *规则7-6：流程自定义例外处理函数，以“OnClear_”为前缀。例16：#function OnClear_QQCallOutClear /电话QQ呼出异常处理函数#function OnClear_sslwCountTime /三省联网统计互拨时长规则7-7：流程中每一层菜单是独立函数，每一个选择项是独立函数。规则7-8：在自定义函数开头须注释该函数的功能说明，详细传递参数、返回值的各种含义。示例参见例15。规则7-9：传入、传出参数尽量使用自定义全局变量，除系统规定外不推荐使用寄存器。承担函数传递

24、参数的全局变量命名要符合变量命名规则。规则7-10：子函数返回值约定，通常约定返回值0表示成功，其他值表示其他不成功原因。 目前已经形成的一些基本约定 A，Returened(9)表示出错需要主动退出流程，如资源分配失败/放音失败等B，Returened(8)表示需要回到主流程C，Returened(7)表示只需回到上层菜单D，Returened(4)表示转坐席后退出E，其他返回值暂定回到上一级菜单F，每个函数后都需要处理Returned(-1)事件例17：/*/连接坐席/*funcConnectAgent#declare IR m_nReturnedCode /标识子函数退出状态 :stWait Equal g_nData , 0 /判断传入参数 - stStar:stStar /action here. / / :stSuccess Assign m_nReturnedCode, 0 /正常连接坐席成功 - stExit:stAgentExit Assign m_nReturnedCode, 4 /转坐席后退出 - s