C与C程序表示规范.doc

C/C+程序表示规范目录目录1C/C+程序表示规范21 引言21.1 目的21.2 背景21.3 定义21.4 参考资料22 程序文件名命名规则33 C/C+标识命名及书写规则33.1 基本规则33.2 含义标识命名及书写规则43.3 规范标识前缀43.3.1 变量前缀43.3.2 类型和类前缀53.3.3 宏和枚举的前缀63.3.4 函数的前缀73.3.5 局部对象的简化命名94 程序注释94.1 注释原则94.2 常量和变量的注释104.3 类型的注释104.4 函数的注释104.5 类的注释114.5 语句的注释:115 模块编写规范:115.1 模块划分的准则:115.2 模块的文件构成:115.3 模块的开发步骤建议125.4 模块设计编写注意事项:126 函数编写规范126.1 函数划分的准则:126.2 函数设计编写注意事项:127 缩进规范127.2 缩进的限制148 可移植性注意事项168.1 预编译头168.2 多平台编程注记181 引言1.1 目的 良好的编程风格是提高程序可靠性非常重要的手段, 也是大型项目多人合作开发的技术基础。本规范的目的在于通过规范定义来避免不好的编程风格, 增强程序的易读性, 便于自己和其它程序员理解。1.2 背景 作为一个软件企业, 程序表示规范是建立企业内部编程的共同语言, 随着人们对编程风格认识的逐渐统一, 程序表示规范已越来越必要和切实可行。1.3 定义 暂缺1.4 参考资料 2 程序文件名命名规则 考虑UNIX和DOS的兼容性, 文件名限制为DOS文件名规则, 文件标识分为两部分，格式如下:前缀 . 后缀 . . 规则: (1) 前缀部分最好不超过8个,后缀部分由本规范定义, 一般为3个符, 通常表示该文件的类型(如是C程序,ASCII文本文件等). (2) 前缀和后缀这两部分字符应仅使用字母、数字和下划线(在DOS中: 前缀部分前8个字符是有效识别符, 后缀部分前3个字符是有效识别符). (3) 当文件是目录时, 仅可使用前缀格式作为目录名, 无后缀. (4) 在Windows 系统中,文件名的前缀命名与模块(类)名规范一致, 虽然这时所有的操作系统文件名支持空格等除0以外的所有字符, 但本规范还是建议使用高级语言中标识符的语法。UNIX和Win32位操作系统(Window95,WindowNT)都保留大小写区分的特征, 原DOS文件名在Win32位操作系统中均被转为大写, 从我国的语言特征来讲(小写通常是汉字录入), 使用全大写的文件名最为恰当, 但很多老的UNIX程序员习惯使用小写来命名(大多数编译程序也只支持小写后缀), 所以本规范只是建议文件名全部使用大写。举例: (1) 8.3命名: obtbl.cxx, obtable.cxx (2) 长文件命名: OBJECTBASETable.cxx,OBTableClass.cxx, TABLE_CLASS.CXX3 C/C+标识命名及书写规则3.1 基本规则 标识名分为两部分: 规范标识前缀+含义标识 标识的总长度不要超过32个字符。 这里的标识是指语言中语法对象的名字, 它们有常量名、变量名、函数名、类和类型名及预处理名, 标识名的基本语法是以字母开始,由字母数字及下划线组成的单词,我们将标识划分成这两个部分是基于如下原因: (1)用规范标识前缀来标名该标识所属的应用系统, 以便在应用系统间互相区别 (2)用规范标识前缀来标名该标识的归类特征,以便与其它类型的标识互相区别 (3)用含义标识来标名该标识所对应的被抽象的实体,以便记忆 (4)用这种命名法来区分本公司标识与外公司标识3.2 含义标识命名及书写规则 (1) 命名: 按其应用的含义由一个或多个词组成. 词可以是中文词或英文词. (2) 书写: 每个词的第一个字母大写, 其余全部小写, 词与词紧连(宏和枚举除外), 宏和枚举值标识全部大写, 词与词可用下划线分开. 中文词由中文描述含义的每个汉字的头一个拼音字母组成. 英文词尽量不缩写, 除非这种缩写比较通用, 不要在同一系统中对同一单词使用不同的表示法(如全写和缩写均使用). 全由大写字母组成的缩写词, 书写仅第一个字母大写, 其余全部小写.3.3 规范标识前缀 规范标识前缀的命名由标识所属类型的前缀命名规范决定, 它总是由1个或多个不超过3个字母的缩写词组成. 规范标识前缀分为四类: (1) 变量前缀 (2) 类型、类前缀 (3) 宏和枚举常量前缀 (4) 函数及共用API前缀 其中(2),(3),(4)说明了那些可供外部程序使用的对象标识的表示规范, 而(1)说明了内部变量的表示规范. 本规范中没有关于全局变量的表示规范, 这是因为全局变量与局部变量混淆所产生的错误是极为难以排除的, 所以在本规范中严禁使用全局变量. 对全局资源的存取要求封装在函数内, 例: 禁止使用的方法: extern int errno; 建议的使用方法: const int GetErrorNo(void); void SetErrorNo(const int);3.3.1 变量前缀 变量前缀采自目前最流行的Microsoft的匈牙利标记法, 由于这套方法专用于PC机上的C编程, 在此, 我们做必要的改动以适应C+及多平台编程的需要. 变量前缀是利用一个或多个小写字母来表示变量的类型信息, 帮助设计者避免C/C+类型匹配和自动转换错误, 例如将长整按布尔值使用时,只要其低16位为0,在PC机上的编译程序一般认为是假. 作为变量总是以小写字母打头, 这使得与常量类(如函数,类名等,它们总是以大写打头)明显区分开来,事实上几乎所有的编译程序在这两类名同名时, 报错信息极不准确, 这种区分可以避免这种错误的产生.前缀代表的数据类型举例以下可作前缀的前缀aarray of char10 achVariable;uunsignedunsigned int uiVariable;llonglong lVariable;ddoubledouble dVariable;ppointer long * plVariable;rreferece int & riVariable;cconstconst int ciVariable;hobject handleHPEN hWindow;fflag variableunsigned int fuiVariable以下不能作前缀的前缀chcharchar chVariable;sshortunsigned short usVariable;iintint i;eenum variableenum A eVariable;wword(unsigned short)unsigned short wVariable;dwdouble word(unsigned long)unsigned long dwVariable;bboolean(int)int bVariable; byunsigned charunsigned char byVariable;hzchinese chars w_char *hzVariable;fnfunction(*fnVariable)(void);sznull-terminated string char *szVariable;vvoid void *pvVariable;recstruct variable (advised)struct A recVariable;注: 如上表示中ch前缀是有二义性的, 它即表示一个char类型又表示一个const handle类型, 但这里的c,h,ch三个缩写已广为使用, 我们在此建议将const handle表示为hc.举例: sizeof当操作p打头的变量返回指针的长度, 而以a打头的变量则会返回数组所占空间的长度, 虽然C/C+对指针和数组比较混乱, 但这种前缀表示法还是可以使你免除一些麻烦。 自定义类型和类的变量, 一般将类名的含义标识第一个字母变为小写作为变量名即可, 如果经常使用该类可自定义对应于该类的变量缩写前缀.举例: OBcObject object, objectName, objectAge; 其中OBcObject为一个类名.3.3.2 类型和类前缀 以该代码所在的应用系统的缩写为准, 长度不超过3个, 全部大写. C语言不支持类, C+现行标准将类与类型已等同对待, 所以命名中我们不必区分这两种。 除变量以小写字母打头以外, 几乎其它标识在本规范都以大写字母打头, 为更加清楚的说明本类标识的特征, 本规范建议类型和类的前缀, 在其应用系统缩写名后紧跟小写字母的类型区别符。举例: typedef unsigned OBuiMachineWord; typedef enum tagOBeOpenMode / file open mode OBE_MODESHAREREAD, OBE_MODEEXCLUSIVE, OBE_MODESHAREUPDATE OBeOpenMode; typedef struct tagOBcHandle / defined the type just for strong type check unsigned int h; *OBcHandle; class OBcIncreaseMemory / a memory can be increased automatic according to data append public: OBcIncreaseMemory(); / init all data member with zero OBcIncreaseMemory(); / delete occupied memory Add(int); / add a integer into Add(char *sz); / add a null terminated string into private: unsigned int uiCursor; void *pvMemory; ;注: c类型标识表示结构或类. 其它类型标识与变量前缀相同 OB是ObjectBASE系统的缩写 虽然在Windows系统中类型名使用的是变量规范(但全部是大写), 但在今天的以类为中心的主要编程方法形式下, 类型和类通常是很多的, 这种命名法的易读性实在是很糟糕的, 因此本规范不采用这种命名法.3.3.3 宏和枚举的前缀 宏是一个极不安全的机制, 它能产生一些非法或非本义的语句, 而你却很难找出错误的原因, 它在绝大多数使用情况下会使代码冗长而低效.在C/C+中增加了枚举、inline、常变量和template机制来避免使用宏, 这些机制可以基本替代宏的使用.但宏是一个语言之上的语言, 它能拼凑语句, 而这种能力在C/C+这种本语言级是无法实现的. 宏和枚举的前缀建议使用应用系统缩写加变量前缀命名方法, 但得全部大写并后加一个下划线. 例: #define OBSZ_ROOTPAHTC:OBJECTBASE / the OBJECTBASE system root path / a good style is using C+ const variable, defined as: / const char * const cszcRootPath = C:OBJECTBASE; #define OBFN_ABS(x) (x)0?(x):-(x) / the abs(x) for all numeric type data / you also can use C+ template to implement the function #ifdef _Windows_ # define OB_DLLPASFUNC _export _pascal #elif UNIX # define OB_DLLPASFUNC #else # error OB_DLLPASFUNC undefined in the compiler #endif typedef tagOBeOpenMode OBE_MODESHAREREAD, OBE_MODEEXCLUSIVE, OBE_MODESHAREUPDATE OBeOpenMode;3.3.4 函数的前缀 函数的前缀与类和类型表示法类似, 它以应用系统的缩写为前缀,后面紧跟一个小写字母f和关于函数返回值的类型描述符, 函数的返回值通常被划分为值返回,错误返回和指针返回这三类: (1) 值返回类的函数总是能正确执行并返回结果值或void(无结果) (2) 错误返回类函数返回值类型总是整数, 该整数值用来表示错误的类型, 通常有如下三种表示方法: (1). 返回 -1为失败(UNIX风格), 如果返回值同时被表示为某个对象的标识(或称为把柄), 则其它值为该对象的标识, 否则只有0表示执行成功, 其它为无定义值.表明错误原因的错误码需调用一个专门的GetErrorNo()之类的函数返回. (2). 返回假为失败, 其它为成功(Windows风格),表明错误原因的错误码需调用一个专门的GetErrorNo()之类的函数返回. (3). 返回结果码, 系统设立一个返回结果码表(内含执行成功的码号及各类错误的码号), 用户通过用结果值与结果码表进行比较来确定函数是否执行成功. 如上三种方法在使用时是互斥的, 即您在一个应用系统中只能选择一种方法. (3) 指针返回类函数返回空指针说明该函数执行失败, 其它值则为一个合法的指针值, 该值通常指向用户所需要的数据或数据空间.表明错误原因的错误码需调用一个专门的GetErrorNo()之类的函数返回. 在此我们规定函数返回值类型描述符为: (1). n为错误返回类, 如无其它后缀则表示返回-1为失败 (2). ni表示返回错误号 (3). nb表示返回假为错误 (4). 变量前缀: 结果返回类, 其中如果返回值为指针类或把柄类, 返回空为错误. (5). 为了不使函数名中的类型描述符过长, 指向对象的指针和把柄应缩写为p和h.举例: (在本例中未给出返值类型说明的按C语法均为整数) OBfnOpen(const char *szObjectName); / Open a Object according to name, return the object handle; / return -1 is a error, you can call OBfGetErrorNo(void) to get error number. OBfniOpen(const char *szObjectName, int *piObjectHandle ); / Open a Object according to name; / if return OBE_SUCCESS, the object handle is put into *piObjectHandle; / else is a error and return the error number. OBfnbOpen(const char *szObjectName, int *piObjectHandle); / Open a Object according to name; / if return true, the object handle is put into *piObjectHandle; / else is a error, you can call OBfGetErrorNo(void) to get error number. OBfOpen(const char *szObjectName); / Open a Object according to name, return the object handle; / it is always success. void OBfvOpen(const char *szObjectName, int *piObjectHandle); / Open a Object according to name; / the object handle is put into *piObjectHandle; / it is always success. OBcObject *OBfpOpen(const char *szObjectName); / Open a Object according to name, return a pointer to the object; / if return null, it is a error, you can call OBfGetErrorNo(void) to get / error number. OBfhOpen(const char *szObjectName); / Open a Object according to name, return the object handle; / if return 0, it is a error, you can call OBfGetErrorNo(void) to get / error number. 之所以作这样的规定是为了我们能够通过函数名来确定函数返回的类型及对错误的处理方法, 这方便了C/C+编程人员对函数的返回值(尤其是错误类)作仔细处理.3.3.5 局部对象的简化命名 本规范的局部对象是指其标识作用域在一个函数内、一个文件内或一个类内的对象, 它们有局部变量、局部常量、局部函数(static类函数)、局部类和类型, 这些对象仍可使用全局类命名法命名, 对于局部函数和局部类及类型也可以去掉应用系统缩写和类型描术符.4 程序注释4.1 注释原则 程序应以其本身的算法设计, 功能划分, 逐级抽象和自说明性为提高易读性的主要手段. 不需要注释的程序是最理想的, 但 C/C+远没有自然语言那么容易书写和理解, 适当的注释是十分必要的. (1) 注释不是重复程序, 它应该提供更多的信息, 否则应该不写. (2) 注释是需要维护的, 错误的注释害人害已. (3) 注释总是加在程序的需要一个概括性说明或不易理解或易理解错的地方. (4) 注释应语言简炼、易懂而又准确, 所采用的语种首选是中文, 如有输入困难、编译环境限制或特殊需求也可采用英文.举例:不好的表示:int i;for (i=1,i 8; i+) .易读的表示typedef enum tagWeekDay Mon, Tue, Wed, Thu, Fri, Sat, Sun WeekDay;WeekDay day;for ( day = Mon; day = Sun; (int)day)+ ) . 数字所能表示的东西实在的太多了, 从理论上讲, 数字可以表示人类所能认知的一切, 第二段程序很清晰的表示了一个关于星期的循环而无需加任何注释, 这是一个增加程序自说明性的例子, 如果你使用英文国家的软件, 你会发现一个令你惊呀的事情, 他们将星期日表示为1, 星期一是2?! 如果你仔细观察日历, 你会发现第1列总是星期日.4.2 常量和变量的注释 在量名字的C/C+或宏声明后应对该名字作适当注释, 注释说明的要点是: (1) 被保存值的含义(必须) (2) 合法取值的范围(可选) (3) 与其它数据,函数或模块的关系(可选) (4) 全局量需要对以上逐点做充分的说明.4.3 类型的注释 对类型的注释应按照数据字典说明来写, 说明要点是: (1) 它描述的对象是什么(必须) (2) 建立在该类型上的操作(函数)有哪些(必须) (3) 对其分量应按3.1要求加以注释(必须) (4) 与其它数据, 函数或模块的关系(可选)4.4 函数的注释 (1) 在函数的原型说明后应作适当注释, 说明该函数的功能, 及各参数的含义. (2) 在函数的定义(实现)部分, 如算法复杂时, 应以注释的方式对其算法结构作出说明. (3) 函数申请过全局资源且有可能导致资源紧张应加以注明(如内存,文件柄等). (4) 函数有副作用一定以十分醒目的方式(如加!号等)注明 4.5 类的注释 类是类型和函数的统一体, 对类的注释与类型相同, 对数据成员的注释与变量相同, 对函数成员的注释与函数相同.4.5 语句的注释: (1) 应对不易理解的分枝条件表达式加注释. (2) 不易理解的循环, 应说明对出口条件(有GOTO的程序还应说明入口条件). (3) 过长的函数实现, 应将其语句按实现的功能分段加以概括性说明5 模块编写规范:5.1 模块划分的准则: (1) 实现相关密切的一组类,类型,常量,变量,宏和函数(高内聚准则) (2) 提供给外部的功能可以通过不超过百行的C/C+说明描述出来(低耦合准则). (3) 过多的外部说明, 应考虑与其他模块合并或重新划分. (4) 实现部分的总代码应在千行以内. 超大的模块应考虑进一步细分.5.2 模块的文件构成: 一个模块是由C/C+源程序文件开发文档组成, 本规范要求一个模块应被分为如下三个文件: (1) 提供给外部的类,类型,常量和宏定义,函数的原型说明,变量的外部声明. 文件名应以模块名后缀.h(C+可以是.hpp) (2) 对外隐蔽的类,类型,常量和宏定义,函数的原型说明,变量的声明及函数实现. 文件名应以模块名后缀.c(C+可以是.cpp|.cxx) (3) 模块开发卷宗, 以模块名后缀.mdf5.3 模块的开发步骤建议 (1) 编写模块开发卷宗 (2) 设计编写提供给外部的类或函数原型及相关的参数类型定义 (3) 给出这些原型的DEMO实现 (4) 设计出提供给外部的类,类型,常量和宏定义, 变量的外部声明. (5) 内部实现设计 (6) 编码 (7) 模块测试(包括编写模块的驱动和支撑程序) (8) 组装测试5.4 模块设计编写注意事项: (1) 与外部的数据交换应以函数的参数形式, 而不要使用全局变量. (2) 内部函数间的数据交换也应以函数的参数形式为主,以使用类数据成员或文件内可见的静态数据变量为辅.(3) 在C+中模块的外部界面应该用一个类定义描述.6 函数编写规范6.1 函数划分的准则: 良好的函数划分, 能够自项向下逐级抽象地展现设计思想, 提高程序的易读性和自说明性. (1) 函数是按功能划分的, 每个函数应该只做一件事情(高内聚准则). (2) 相关的一组函数关联应不多(低耦合准则). (3) 在不破坏(1),(2)原则前提下, 一个函数代码长度不宜超过50行, 以20行左右为标准长度. 6.2 函数设计编写注意事项: (1) 提供给外部使用的函数, 绝不应使用全局变量交换数据. (2) 函数间原则上不应有调用顺序关系.7 缩进规范 使用缩进表示程序对程序的易读性起着至关重要的作用, 这一点每个编程人员早有共识, 在表示缩进时有一个小的技术细节要提请注意, 各种编辑器对TAB与空格的对应关系并不相同, 容易导致程序在另一种编辑器中缩参差不齐. 所以我们要求不可使用TAB键来表示缩进, 建议使用3个空格键表示, 7.1 控制结构的缩进 程序应以缩进形式展现程序的块结构和控制结构, 我们建议如下三种缩进风格,它们都有一个共同的优点: 在不影响展示程序结构的前提下尽可能地减少缩进的层次. (以if为例) (1) if ( expression ) statements else statements (2) if ( expression ) statements else statements (3) if ( expression1 ) statements else statements 方法(2)有另外一个优点就是所用行数更少, 这为许多喜欢写比较长的函数的人所偏爱, 但它有一个比较大的弱点, 在一个表达式过长需要折行写时, 区分表达式和语句比较困难. 如: if ( function1( expression1, expression2, expression3 )=0 ) statements else statements 而用(1),(3)种表示则易读一些: if ( function1( expresstion1, expression2, expression3 ) = 0 ) statements else statements 7.2 缩进的限制 一个程序的宽度如果超出页宽或屏宽, 这将是很难读的, 所以本规范要求使用折行缩进的方法、合并表达式或编写子程序的方法来限制程序的宽度. (1) 任何一个程序最大行宽不得超过76列, 超过者必须折行书写. (2) 任何一个函数的缩进不得超过5级, 超过者必须将其子块写为子函数. 事实上大多数过多的缩进都是不注意合并表达式的条件所造成的, 从程序设计方法来讲, 这些程序员设计程序的方法是枚举所有的可能再加上分别处理. 而在这种情况下另外一种设计方法是观察有多少种可能进行的处理, 然后再来决定这些处理所必须具备的条件, 按这种先处理后条件的方法进行程序设计, 缩进层次总是很少的, 而且重复书写处理部分的代码总是降到最低点(但重复书写的表达式确可能很多, 但编译程序在提取公共表达式的能力完全可以弥补这种方法所造成的效率上的损失). 后一种设计方法是一个好的程序员首选方法, 但掌握这种技术确不是一件简单的事. 需折行的过长的表达式或函数参数过多时, 我们建议如下表示规范: (1) 过长的条件表达式(以if举例): if ( expression1 & (expression2 | expression3) & expression4 ) statements ) (2) 过长的函数原型说明: OBcObject * OB_DLLPASFUNC FunctionName ( / function name Type1 Parameter1, / the paramter means is written here Type2 Parameter2, / . . );或 OBcObject * OB_DLLPASFUNC FunctionName ( Type1 Parameter1, / the paramter means is written here Type2 Parameter2, / . . ); (3) 过长的函数调用: OBcObject *pObject = FunctionName( parameter1, parameter2,. parameterN,. ); if ( FunctionName( parameter1,parameter2,. parameterN,.) = 0 & expression. ) ( )或 OBcObject *pObject = FunctionName ( parameter1, parameter2, . ); if ( FunctionName ( parameter1, parameter2, . ) = 0 & expression. ) ( )8 可移植性注意事项8.1 预编译头 如果您的代码可以在多个操作系统及多个编译程序中共享, 一个预编译头文件是必不可少的, 该文件用来标识当前所用的操作系统、编译程序、CPU类型下的本地特征,如下以MS-DOS,WIN16,WIN32,Solaris2.x,HPUX,IRIS操作系统、Borland C+ 2.0以上,Microsoft C/C+ 7.0以上, AT&T C+2.0以上UNIX编译器和INTEL,HP,SGI,SPARC机为平台的源码级共享所需的预编译头.#ifndef _compmacr_h#define _compmacr_h / begin the file COMPMACR.H 94.12.11#ifndef _cplusplus #error This is not a C+ compiler#endif#ifdef hpux #define ENVIRONMENT 1 / indicate the environment has been defined #define CPPATT 200 / AT&T C+ above version 2.0 #define BYTEREVERT 1 / the numeric byte order is revert with ISO #define OS_HPUX / this is hp machine & OS #ifndef UNIX / it is unix OS #define UNIX #endif#endif#ifdef _SGI_SOURCE #define ENVIRONMENT 1 / indicate the environment has been defined #define CPPATT 200 / AT&T C+ above version 2.0 #define BYTEREVERT 0 / the numeric byte order is same as ISO #define OS_SGI / this is SGI machine & OS #define OS_IRIS / this is SGI machine & OS #ifndef UNIX / it is unix OS #define UNIX #endif#endif#ifdef sun #define ENVIRONMENT 1 / indicate the environment has been defined #define CPPATT 200 / AT&T C+ above version 2.0 #ifdef sparc / if is SPARC CPU #define BYTEREVERT 0 / the numeric byte order is same as ISO #else / if is other type CPU #define BYTEREVERT 1 / the numeric byte order is revert with ISO #endif #include / use errno.h to find OS version #if !defined(ENOSYS) | ENOSYS=90 #define OS_Solaris1x / this is SunOS 4.x or Solaris 1.x OS #endif #if ENOSYS=89 #define OS_Solaris2x / this is SunOS 5.x or Solaris 2.x OS #endif #ifndef UNIX / it is unix OS #define UNIX #endif#endif #ifde