软件编程规范.doc

软件编程规范前言为了规范提高代码的质量，加强代码的可维护性，特制定此规范。规范中包含规则和建议，规则是在编程中必须遵守的，建议则是一种提议，可根据具体情况考虑采纳。一、基本数据类型定义规则1-1：为提高代码的可移植性，屏蔽不同系统之间的基本数据类型的长度差异，减少代码在不同系统之间的移植工作量，需要对基本数据类型进行类型声明，基本类型的类型声明标准如下：（两种定义方式进行选择）typedef void _VOID;typedef char _CHAR8;typedef unsigned char _UCHAR8;typedef signed char _SCHAR8;typedef int _INT32;typedef unsigned int _UINT32;typedef signed int _SINT32;typedef short _SHORT16;typedef unsigned short _USHORT16;typedef signed short _SSHORT16;typedef long _LONG32;typedef unsigned long _ULONG32;typedef signed long _SLONG32;typedef float _FLOAT32;typedef double _DOUBLE64;二、变量与函数命名规则规则2-1：变量类型前缀命名所有变量命名采用匈牙利命名法，数据类型与前缀的定义如下a : array，数组b : bool，布尔by : byte，字节c : char，字符dw : double word(unsigned long)，双字fn : function，函数g_ : global，全局变量i : integer，整型l : long，长字lp : long pointer，长指针m_ : module，模块变量g_ : global，全局变量n : short int，短整型p : pointer，指针s : string，字符串sz : zero terminated string，以零字符结束的字符串u : unsigned int，无符号整型ul : unsigned long，无符号长整型w : word(unsigned short)，字因为有重复，建议采用红色的前缀。增加三种st : struct，结构en : enum，枚举b: 位域变量类型之间可以组合。举例：UINT32 * apdwTempPtr32;UINT32 b7Temp: 7; 规则2-2：变量名称与书写所有变量采用大小写命名方式，单词的首字母大写，其他字母小写，单词与单词之间不采用下划线连接。举例：UCHAR8 * pucMyString;规则2-3：模块与全局的区别各模块对外提供的全局变量以g_作为前缀进行表示，模块内部使用的公共变量以m_作为前缀，函数内部的局部变量不使用任何前缀。规则2-4：函数名命名原则函数命名与变量命名一样，采用大小写命名，单词的首字母大写，其他字母小写。单词与单词直接相连，不采用下划线相连。各模块对外提供的接口函数以该模块的缩略语为前缀，中间以下划线相连。各模块的缩略语定义如下：ALM：告警CLI：命令行COMM：通信DB：数据库DEV：设备管理LD：加载OS：操作系统：TST：测试举例：_VOID * OS_Malloc( _USHORT16 wMid, _ULONG32 dwSize );规则2-5：宏定义所有宏定义采用大写字母，单词与单词之间以下划线相连。举例：#define AG_VERSION “AG1000V100R001”规则2-6：枚举类型定义所有枚举类型定义以typedef进行类型重定义，枚举成员全部大写，以EN为前缀，单词与单词之间以下划线连接。枚举的最后一个成员后面不允许有逗号。举例：typedef enum DATE EN_SUNDAY,EN_MONDAY,EN_TUESDAY, EN_WEDNESDAY,EN_THURSDAY,EN_FRIDAY,EN_SATURDAY DATE；规则2-7：结构类型定义结果类型全部以typedef进行类型重定义，重定义的类型全部大写，以ST开头，ST与其他单词之间以下划线相连，其他单词直接相连。如果需要定义该结构类型的指针类型，在ST前加P。举例：typedef struct_UCHAR8 aucName8;_UCHAR8 ucAge; ST_PERSONALRECORD, PST_PERSONALRECORD;规则2-8：除循环变量外，禁止使用i，j，k等无意义的单字母作为变量名。三、文件与目录结构四、排版规则4-1：注释风格为了保证在不同编译器之间的移植，所有注释采用ANSI C的/* */注释方法，不允许采用C+的/ 注释风格。注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。建议4-1：注释中不要使用缩写，尤其是非常用的缩写。建议4-2：注释在意思表达明确的情况下，可以采用中文或者英文注释。规则4-2：注释的内容要清楚，明了，含义准确，防止二义性。代码发生改变时，相应的注释也应该相应改变。无用的注释要删除。规则4-3：对于所有有物理含义的变量、常量，数据结构，以及结构成员，如果其命名不是充分自注释的，在定义时都必须加以注释，说明其物理含义。规则4-4：注释和其说明的内容采用同样的缩进。规则4-5：预编译的结束语句，程序块的结束行右方加注释标记，以表明一段程序的结束。规则4-6：文件的头部必须有文件说明，说明的内容包括版本说明，版本号，生成日期，作者，文件内容与功能，修改历史。文件说明格式如下。/* (c) COPYRIGHT 2000-2008 by Hrbour Networks System, Inc. All rights reserved.This software is confidential and proprietary to Hrbour Networks System, Inc. No part of this software may be reproduced,stored, transmitted, disclosed or used in any form or by any means other than as expressly provided by the written license agreement between Hrbour Networks System and its licensee.FileName: Author:Version:Date:Description:Others:History:1.Date:Author:Modification: */规则4-8：代码书写应该采用缩进风格，缩进的空格数为四个空格。缩进和对齐不允许采用TAB键，必须使用空格进行缩进和对齐。规则4-9：函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case语句下的情况处理语句也要遵从语句缩进要求。规则4-10：if、for、do、while、case、switch、default等语句自占一行，且if、for、do、while等语句的执行语句部分无论多少都要加括号。规则4-11：程序块的分界符（如C/C+语言的大括号和）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。规则4-12：在两个以上的关键字、变量、常量进行对等操作时（&，|，=，等），它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如，.），后不应加空格。建议4-3：一行语句不宜太长，以80字符为宜。建议4-4：较长的语句（80字符）要分成多行书写，分行点最好选择操作符处。长表达式要在低优先级操作符处划分新行，操作符放在新行之首。如果是关系操作符，操作符两侧的语句左对齐。否则划分出的新行要进行适当的缩进，使排版整齐，语句可读。规则4-13：相对独立的程序块之间、变量说明之后必须加空行规则4-14：不允许把多个短语句写在一行中，即一行只写一条语句。规则4-15：函数参数太长时，应该进行换行，每个参数占用一行，参数之间左对齐。五、编程规则5-1：SWITCH语句必须有default语句。每个case语句必须有break语句，如果两个相邻的case语句共用语句，必须给出明确的注释说明。规则5-2：存在操作符的宏定义必须加括号（）。规则5-3：注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。规则5-4：代码中不允许直接出现数字，必须用有意义的枚举或宏来代替。规则5-5：防止局部变量与公共变量同名。规则5-6：函数传参时，禁止直接使用结构进行传参，而应该使用结构指针。建议5-1：在进行局部变量的赋值，内存COPY时必须判断赋值是否越界，以免造成堆栈破坏。规则5-7：变量定义必须放在函数的入口处，禁止C+风格的即用即定义（在程序中间进行变量定义）。规则5-8：模块对外提供的接口函数在函数的入口处必须进行参数有效性判断，内部函数如果可以保证在函数调用处的参数判断，可以不在函数入口处进行参数有效性判断。建议5-2：循环变量要进行边界检查，防止造成死循环以及边界的差一错误。规则5-9：严禁使用未经初始化的变量作为右值。建议5-3：结构定义时应尽量保证结构大小以及结构成员的四字节对齐，以提高代码效率。建议5-4：当声明用于分布式环境或不同CPU间通信环境的数据结构时，必须考虑机器的字节顺序、使用的位域及字节对齐等问题 。规则5-10：对函数的返回值要进行判断，保证各种错误码都可以得到正确的处理。建议5-5：尽量减少模块间的共享全