软件编程建议.doc

文档编号产品版本受控状态V1.0内部1I hup://www. lily. net. cn产品名称：软件编程建议共页批注［liaoll：密级可以选择以下儿 种：无，一般・内部，组内，秘 密，绝密等软件编程建议（仅供内部使用）北京世纪百合科技有限公司Beijing Centurial Lily Technology Co.,Ltd.版权所有不得复制文档修改记录版本号H期所改贝注记提交人批准人1. 引言 51.1 目的 51.2 范围 52. 建议 52.1 代码 52.2 代码的效率 132.3 可测试性 142.4 操作系统下的编程 152.5 代码的编辑.编译和审査 171.引言1.1目的本建议的日的在于在公司开发的所有软件产品中推荐使用开发方法以及廿发经 验，使用该建议将有助于提高软件生产效率，减少廿发过程的错课以及提高软件 产品的最终品质1.2范本规范内容涉及范用包括：代码的可靠性、代码的效率、代码的可测试性以及 代码的编译、编译和审查，以及多任务操作系统vxWorks下的编程2.建议代码2.1.1在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符 之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的 立即操作符(如一>),后不应加空格。

说明：采用这种松散方式编写代码的日的是使代码更加清晰示例：比较操作符,赋值操作符”=“、“+=“，算术操作符”+“、"％“，逻辑操作符”&&“、 “&“，位域操作符等双目操作符的前后加空格if (wCurrentTime >= ISDN_MAXTIMEVALUE) //比较运算符〃>=〃wLength = wWidth + wHigh; //赋值操作符"="、算术操作符wLength *= 2; //算术操作符"*="wLength = wWidth A 2; //赋值操作符算术操作符%”(地址运算符)等单U操作符前肩不加空格pcName = 1 a 1; bFlag = !bEmpty; pbyAddr = &byMem;i + + ；//内容操作I”与内容之间//非操作”！ ”与内容之间//地址操作”&”与内容之间// 与内容之间(3)”-前后不加空格pCaller->byId = byld; // "-〉”指针前后不加空格(4) if、for、whiles switch等与后面的括号间应加空格,使if等关键字更为 突岀、明显示例：if ( (wLength >= wWidth) && (wLength > wHigh))2.1.2源程序的有效注释量一般应在代码总量的20%以上，包括对文件的注 释、对函数的注释以及对全局、局部变量的注释等。

说明：(1)注释的原则是有助于对程序的阅读理解，在该加的地方祁加了，注释不宜 太多也不能太少，注禅语言必须准确、易懂、简洁对确实没有用的代码应该删除，不能进行注释对于可能有用的代码应该 使用DEBUG开关，也不要进行注释提倡单行注释方式”\\”，尽量不要使用7护和注释不允许使用if(0)等语句示例：以下注释方式不规范wLength++;//printf ("the length is %d\n,zz wLength);应该改为：wLength++;或wLength++;#ifdef ISDN_DEBUG printf (the length is %d\nz\ wLength);#endif2丄3对分支语句(条件分支、循环语句等)应该编写注释说明：这些语旬往往是程序实现某一特建功能的关键，对于维护人员來说，良好的注 释帮助更好的理解程序，有时甚至优于看设计文档示例：如下注程意义不大// if bReceiveFlag is TRUEif (bReceiveFlag)而如下的注脅则给山了额外有用的信息/* if mtp receive a message from links */if (bReceiveFlag)当代码比较长，特别是有多重嵌套时，应当在一些段落的结束处加注释，便于阅读。

示例：if (bFlag)while (wTemp) } // end of while(wTemp)} //end of if (bFlag)2.1.4有实际意义的变量命名禁止取单个字符(如i、j、k...),除了要有具体 含义的字母外还要有能表明其变量类型以及数据类型的字母i、j、k等 单个字符作为局部循环变量是允许的2.1.5用正确的反义词组命名具有互斥意义的变量或相反动作的函数等当函 数名由名词和动词组成时，名词放在动词的前面说明：下面是一些在软件中常用的反义词组add / deletebegin / endmin/ maxinsert / deletefirst / lastget/ releaseincrement / decrementput / getup /downcreate / destroylock / unlockopen/ closesource / destinationold / newstart / stopnext / previousshow / hidecut/ pastesend / receive示例：int iMinSum;int UserAdd(BYTE *pbyUsetNAme);int UserDelete(BYTE *pbyUserName);2丄6结构中元素的个数应适中，若结构中元素个数过多可考虑依据类型相近 原则把元素组成不同的子结构，以减少原结构中元素的个数。

接口之间 的数据结构和消息结构应该定义为紧凑方式说明：口的是为了增加结构的对理解性、可维护性接口之间的数据结构和消息结构 定义为紧凑方式可以保证接口传递数据时元素位置不会出现偏移示例：typedef struetWORDwDestTaskID;WORDwSourTasklD;WORDwMsgType;WORDvjMsgLength;WORDvjTaskID;BOOLEANbDataFlag;BYTE*pbyData;DWORDdwDatdSize;}PACK_STRUCTCFM_SENT_BGP_DATA;如果认为上述结构元素过多，可以划分为如下形式: typedef struct{WORD wDestTaskID;WORD wSourTaskID;WORD wMsgType;WORD wMsgLength;}PACK_STRUCTCOMMON_HEAD;stCommHead; wTaskID; bDataFlag; *pbyData;dwDataSize;typedef struct {COMMON_HEAD WORDBOOLEANBYTEDWORD }PACK_STRUCTCFM_SENT_BGP_DATA;2.1.7定义用于分布式环境或不同类别CPU间通信环境的数据结构时，要机器 的字节顺序、位域顺序等问题。

说明：比如InlelX86CPU与MOTOROLA PPC CPU,在处理位域及整数时，其在内 存存放的“顺序”止好相反示例：假如有如下短整数及结构short int iExmmple;typedef struct{BYTE byProtocol:5;BYTE byLayerId:2;BYTE byExt:1;}ISDN_BEARER;如下是Intel CPU生成短整数及位域的顺序内存： 0 1 2 ...（从低到高，以字节为单位）iExample低字节 ＞高字节内存： 0-4bit 5-6bit 7bit （字节的各“位”）ISDN_BEARER byProtocol byLAyerld byExt如下是PPC CPU生成短整数及位域的方式内存： 0 1 2・..（从低到高，以字节为单位）iExample低字节 ＞高字节内存： 7-3bit 2-lbit Obit （字节的各”位”）ISDN_BEARER byProtocol byLayerld byExt2.1.8函数的规模一般限制在200行以内，函数功能要求单一说明：不包括注禅和空行2.1.9避免函数有太多的参数，参数个数尽量控制在5个以内。

2.1.10功能特别简单的函数可以通过宏、冒号表达式或内联函数等方式实现， 以提高效率说明：通过宏或内联函数代替函数，省去了参数压栈、生成汇编语言的CALL调用、 返回参数、执行“Wni等过程，从而提高了速度示例：如下语句的功能太单一int isdn_M4xP32m (int iTx, int iRx){return ( (iTx > iRx) ? iTx : iRx);}可以通过表达式iResult = (iTx > iRx ) ? iTx : iRx ;或宏#define MAX(a,b) ( ( (a) > (b)) ? (a) : (b))iResult = MAX(iTxz iRx);也可以通过内联函数inline int isdn_MaxParam(int iTx,int iRx){return ( (iTx > iRx) ? iTx : iRx);}來实现2.1.11函数的扇入、扇出系数要合理，设计高扇入、合理扇出(小于7)的函 数说明：扇出是指一个函数立接调用(控制)其它函数的数日，而扇入是指有多少 上级函数调用它扇出过人，表明函数过分复杂，需耍控制和协调过多的下级函 数；而扇击过小，如总是1,表明函数的调用层次可能过多，这样不利程序阅读和 函数结构的分析，并且程序运行时会对系统资源如堆栈空间等造成圧力。

函数较 合理的扇岀(调度函数除外)通常是3〜5扇出太人，一般是由于缺乏中间层次， 训适当增加中间层次的函数扇出太小，可把下级函数进一步分解多个函数，或 合并到上级函数中当然分解或合并丙数时，不能改变要实现的功能，也不能违 背函数间的独立性扇入越人，表明使用此函数的上级函数越多，这样的函数使 用效率高，但不能违背函数间的独立性而单纯地追求高扇入公共函数及底层函 数应该有较高的扇入较良好的软件结构通常是顶层函数的扇出较高，中层函数 的扇出较少，而底层函数则扇入到公共模块中2.1.12减少函数本身或函数间的递归调用说明：递归调用特别是函数间的递归调用(如A->B->C->A),影响程序的可理解 性；递归调用…般都占用较多的系统资源(如栈空间。