1、软件开发命名规范软件开发规范C+命名规范在研究项目团队协作开发的情况下(这里的团队协作也适合于应用项目的开发),编程时应该强调的一个重要方面是程序的易读性,在保证软件速度等性能指标能满足用户需求的情况下,能让其他程序员容易读懂你所编写的程序。若研究项目小组的所有开发人员都遵循统一的、鲜明的一套编程风格,可以让协作者、后继者和自己一目了然,在很短的时间内看清楚程序结构,理解设计的思路,大大提高代码的可读性、可重用性、程序健壮性、可移植性、可维护性。制定本编程规范的目的是为了提高软件开发效率及所开发软件的可维护性,提高软件的质量。本规范由程序风格、命名规范、注释规范、程序健壮性、可移植性、错误处理
2、以及软件的模块化规范等部分组成。本软件开发规范适合讨论C/C+程序设计。1 文件结构每个C+/C程序通常分为两个文件。一个文件用于保存程序的声明(declaration),称为头文件。另一个文件用于保存程序的实现(implementation),称为定义(definition)文件。C+/C程序的头文件以“.h”为后缀,C程序的定义文件以“.c”为后缀,C+程序的定义文件通常以“.cpp”为后缀(也有一些系统以“.cc”或“.cxx”为后缀)。1.1 文件信息声明文件信息声明位于头文件和定义文件的开头(参见示例1-1),主要内容有:(1) 版权信息;(2) 文件名称,项目代码,摘要,参考文献;
3、(3) 当前版本号,作者/修改者,完成日期;(4) 版本历史信息;(5) 主要函数描述。/ Copyright (c) 2004, Department of Mathematics, Zhejiang University/ All rights reserved./ Filename :filename.h/ Project Code :The project code about this file/ Abstract :Describe the content of this file summarily/ Reference :./ Version :1.1/ Author :the
4、 name of author(mender)/ Accomplished date : September 2, 2004/ Replaced version : 1.0 / Original Author : the name of original author(mender)/ Accomplished date : September 10, 2003/ Main functions :/ Function 1 Return code Function name(Parameter Explain)/ Function 2 Return code Function name(Para
5、meter Explain)/ ./ Function n Return code Function name(Parameter Explain)/示例1-1 文件信息声明 【规则1.1-1】 文件信息声明以两行斜杠开始,以两行斜杠结束,每一行都以两个斜杠开始; 【规则1.1-2】 文件信息声明包含五个部分,各部分之间以一空行间隔; 【规则1.1-3】 在主要函数部分描述了文件所包含的主要函数的声明信息,如果是头文件,这一部分是可以省略的。1.2 头文件的结构头文件由三部分内容组成: (1) 头文件开头处的文件信息声明(参见示例1-1);(2) 预处理块;(3) 函数和类结构声明等。假设头文
6、件名称为 filesystem.h,头文件的结构参见示例1-2。 【规则1.2-1】 为了防止头文件被重复引用,应当用ifndef/define/endif结构产生预处理块;“#ifndef”或者“#define”后以TAB键代替SPACE键做空格;如果头文件名称是由多个单词组成,则各单词间以下划线“_”连接,例如有头文件名称为“filesystem.h”,则定义如下:“#ifndef _FILE_SYSTEM_H_”; 【规则1.2-2】 用 #include 格式来引用标准库的头文件(编译器将从标准库目录开始搜索); 【规则1.2-3】 用 #include “filename.h” 格式
7、来引用非标准库的头文件(编译器将从用户的工作目录开始搜索); 【建议1.2-1】 头文件中只存放“声明”而不存放“定义”; 【建议1.2-1】 头文件中应包含所有定义文件所定义的函数声明,如果一个头文件对应多个定义文件,则不同定义文件内实现的函数要分开声明,并作注释以解释所声明的函数从属于那一个定义文件; 【建议1.2-3】 宏定义和函数声明分离,在两个头文件中定义,如果没有类成员函数,可以将类和结构的定义与函数声明分离,也就是说一个头文件专用于宏定义,一个头文件专用于类和结构的定义,一个头文件专用于函数声明; 【建议1.2-4】 在C+ 语法中,类的成员函数可以在声明的同时被定义,并且自动成
8、为内联函数。这虽然会带来书写上的方便,但却造成了风格不一致,弊大于利。建议将成员函数的定义与声明分开,不论该函数体有多么小。头文件的结构如下:/文件信息声明见示例1-1,此处省略。#ifndef _FILE_SYSTEM_H_ /avoid referencing the file filesystem.h repeat#define _FILE_SYSTEM_H_#include /reference standard head file#include “myheader.h” /reference non-standard head filevoid Function1(); /glob
9、al function declareclass CBox /class structure decalre;#endif示例1-2 C+/C头文件的结构1.3 定义文件的结构定义文件有三部分内容:(1) 定义文件开头处的文件信息声明(参见示例1-1);(2) 对一些头文件的引用;(3) 程序的实现体(包括数据和代码)。假设定义文件的名称为 filesystem.c,定义文件的结构参见示例1-3。/文件信息声明见示例1-1,此处省略。#include “filesystem.h” /reference a head file/global function realizationvoid Fu
10、nction1()/class member function realizationvoid CBox:Draw()示例1-3 C+/C定义文件的结构1.4 头文件的作用早期的编程语言如Basic、Fortran没有头文件的概念,C+/C语言的初学者虽然会用使用头文件,但常常不明其理。这里对头文件的作用略作解释:(1) 通过头文件来调用库功能。在很多场合,源代码不便(或不准)向用户公布,只要向用户提供头文件和二进制的库即可。用户只需要按照头文件中的接口声明来调用库功能,而不必关心接口怎么实现的。编译器会从库中提取相应的代码;(2) 头文件能加强类型安全检查。如果某个接口被实现或被使用时,其方
11、式与头文件中的声明不一致,编译器就会指出错误,这一简单的规则能大大减轻程序员调试、改错的负担。1.5 目录结构如果一个软件的头文件数目比较多(如超过十个),通常应将头文件和定义文件分别保存于不同的目录,以便于维护。例如可将头文件保存于include目录,将定义文件保存于source目录(可以是多级目录)。如果某些头文件是私有的,它不会被用户的程序直接引用,则没有必要公开其“声明”。为了加强信息隐藏,这些私有的头文件可以和定义文件存放于同一个目录。2 命名规则比较著名的命名规则当推“匈牙利” 命名法,该命名规则的主要思想是“在变量和函数名中加入前缀以增进人们对程序的理解”。例如所有的字符变量均以
12、ch为前缀,若是指针变量则追加前缀p。如果一个变量由ppch开头,则表明它是指向字符指针的指针。“匈牙利”法最大的缺点是烦琐,例如int i, j, k; float x, y, z;倘若采用“匈牙利”命名规则,则应当写成int iI, iJ, ik; / 前缀 i表示int类型float fX, fY, fZ; / 前缀 f表示float类型如此烦琐的程序会让绝大多数程序员无法忍受。总的说来,没有一种命名规则可以让所有的程序员赞同,且命名规则对软件产品而言并不是“成败悠关”的事,而且在不同的平台和不同的环境下编写的程序所应遵循的规则也不尽相同,所以我们只是追求制定一种令大多数项目成员满意的命
13、名规则,并在项目中贯彻实施。2.1 共性原则本节论述的共性规则是被大多数程序员采纳的,我们应当在遵循这些共性规则的前提下,再扩充特定的规则,如2.2节 【规则2.1-1】 标识符应当直观且可以拼读,可望文知意,不必进行“解码”; 【规则2.1-2】 标识符的长度应当符合“min-length & max-information”原则; 【规则2.1-3】 命名规则尽量与所采用的操作系统或开发工具的风格保持一致; 【规则2.1-4】 程序中不要出现仅靠大小写区分的相似的标识符。 【规则2.1-5】 程序中不要出现标识符完全相同的局部变量和全局变量,尽管两者的作用域不同而不会发生语法错误,但会使人
14、误解; 【规则2.1-6】 变量的名字应当使用“名词”或者“形容词名词”; 【规则2.1-7】 全局函数的名字应当使用“动词”或者“动词名词”(动宾词组); 【规则2.1-8】 用正确的反义词组命名具有互斥意义的变量或相反动作的函数等; 【建议2.1-1】 尽量避免名字中出现数字编号,如Value1,Value2等,除非逻辑上的确需要编号;注:2.1.1 标识符最好采用英文单词或其组合,便于记忆和阅读,切忌使用汉语拼音来命名,程序中的英文单词一般不要太复杂,用词应当准确,例如不要把CurrentValue写成NowValue;2.1.2 标示符的长度应当以最小的长度实现最多信息,一般来说,长名
15、字能更好地表达含义,但并非长的变量名就一定要比短的变量名要好,此外单字符的名字也是有用的,常见的如i,j,k,m,n,x,y,z等,它们通常可用作函数内的局部变量;2.1.3 不同的操作系统的程序设计风格是不一样的,例如Windows应用程序的标识符通常采用“大小写”混排的方式,如AddChild,而Unix应用程序的标识符通常采用“小写加下划线”的方式,如add_child,别把这两类风格混在一起使用;2.2 Windows变量命名规则 【规则2.2-1】 变量的命名规则要求采用“匈牙利法则”,即开头字母用变量的类型,其余部分用变量的英文意思或其英文意思的缩写,尽量避免采用中文拼音,要求单词
16、的第一个字母大写;即:变量名变量类型变量英文意思(或缩写)变量类型请参见附表1变量类型表; 【规则2.2-2】 类名和函数名用大写字母开头的单词组合而成;对struct、union、class变量的命名要求定义的类型用大写,结构采用S开头,联合体采用U开头,类采用C开头;例如:struct SPoint int m_nX; int m_nY;union URecordLen BYTE m_byRecordNum; BYTE m_byRecordLen; class CNode /类成员变量或成员函数 ; 【规则2.2-3】 指针变量命名的基本原则为:一重指针变量的基本原则为: 变量名 “p”变
17、量类型前缀命名对多重指针变量的基本原则为:二重指针:变量名“pp”变量类型前缀命名三重指针: 变量名“ppp”变量类型前缀命名.例如一个short*型的变量应该表示为pnStart; 【规则2.2-4】 全局变量用g_开头;例如一个全局的长型变量定义为g_lFileNum,即:变量名g_变量类型变量的英文意思(或缩写); 【规则2.2-5】 静态变量采用s_开头;例如一个静态的指针变量定义为s_plPrevInst,即:变量名s_变量类型变量的英文意思(或缩写); 【规则2.2-6】 类成员变量采用m_开头;例如一个长型成员变量定义为m_lCount,即:变量名m_变量类型变量的英文意思(或缩
18、写); 【规则2.2-7】 对const的变量要求在变量的命名规则前加入c_(若作为函数的输入参数,可以不加),即:变量名c_变量命名规则,例如:const char* c_szFileName; 【规则2.2-8】 对枚举类型(enum)中的变量,要求用枚举变量或其缩写做前缀,且用下划线隔离变量名,所有枚举类型都要用大写,例如:enum EMDAYS EMDAYS_MONDAY; EMDAYS_TUESDAY; .; 【规则2.2-9】 对常量(包括错误的编码)命名,要求常量名用大写,常量名用英文意思表示其意思,用下划线分割单词,例如:#define CM_7816_OK 0x9000; 【
19、规则2.2-10】 为了防止某一软件库中的一些标识符和其它软件库中的冲突,可以为各种标识符加上能反映软件性质的前缀。例如三维图形标准OpenGL的所有库函数均以gl开头,所有常量(或宏定义)均以GL开头。3 程序风格程序风格虽然不会影响程序的功能,但会影响程序的可读性,追求清晰、美观,是程序风格的重要构成因素。3.1 空行空行起着分隔程序段落的作用。空行得体(不过多也不过少)将使程序的布局更加清晰。空行不会浪费内存,虽然打印含有空行的程序是会多消耗一些纸张,但是值得。 【规则3.1-1】 在每个类声明之后、每个函数定义结束之后都要加空行。参见示例3.1(a); 【规则3.1-2】 在一个函数体
20、内,逻揖上密切相关的语句之间不加空行,其它地方应加空行分隔。参见示例3.1(b);/ blank linevoid Function1() / blank linevoid Function2() / blank linevoid Function3() / blank linewhile (condition) statement1; / blank line if (condition) statement2; else statement3; / blank line statement4; 示例3.1(a) 函数之间的空行 示例3.1(b) 函数内部的空行3.2 代码行 【规则3.2-
21、1】 一行代码只做一件事情,如只定义一个变量,或只写一条语句,这样的代码容易阅读,并且方便于写注释; 【规则3.2-2】 if、for、while、do等语句自占一行,执行语句不得紧跟其后,不论执行语句有多少都要加,这样可以防止书写失误; 【规则3.2-3】 if、for、while、do等语句的“”要单独占用一行; 【建议3.2-1】 所有函数内的变量都在函数开始处定义; 【建议3.2-2】 尽可能在定义变量的同时初始化该变量(就近原则),如果变量的引用处和其定义处相隔比较远,变量的初始化很容易被忘记。如果引用了未被初始化的变量,可能会导致程序错误,本建议可以减少隐患。示例3.2(a)为风格
22、良好的代码行,示例3.2(b)为风格不良的代码行。int nWidth; / widthint nHeight; / heightint nDepth; / depthint nWidth,nHight,nDepth;/width,height,depthx = a + b;y = c + d;z = e + f;X a + b; y = c + d; z = e + f;if (nWidth nHight) DoSomething();if (nWidth =”、“=”、“+”、“*”、“%”、“&”、“|”、“”这类操作符前后不加空格; 【建议3.3-1】 对于表达式比较长的for语句和i
23、f语句,为了紧凑起见可以适当地去掉一些空格,如for (i=0; i10; i+)和if (a=b) & (c= 2000) / favorable styleif(year=2000) / ill styleif (a=b) & (c=b&c=d) / ill stylefor (i=0; i10; i+) / favorable stylefor(i=0;i10;i+) / ill stylefor (i = 0; I 10; i +) / favorable stylex = a b ? a : b; / favorable stylex=aFunction(); / Do not us
24、e b - Function();示例3.3 代码行内的空格3.4 对齐 【规则3.4-1】 程序的分界符和应独占一行并且位于同一列,同时与引用它们的语句左对齐; 【规则3.4-2】 之内的代码块在右边数格处左对齐; 【规则3.4.3】 代码的的对齐采用TAB键而不采用空格键对齐,一般TAB键设置为向后空4个空格。示例3.4(a)为风格良好的对齐,示例3.4(b)为风格不良的对齐。void Function(int x) / program codevoid Function(int x) / program codeif (condition) / program codeelse / pr
25、ogram codeif (condition) / program codeelse / program codefor (initialization; condition; update) / program codefor (initialization; condition; update) / program codeWhile (condition) / program codewhile (condition) / program code如果出现嵌套的,则使用缩进对齐,如: 示例3.4(a) 风格良好的对齐 示例3.4(b) 风格不良的对齐3.5 长行拆分 【规则3.5-1】 代码行最大长度宜控制在70至80个字符以内; 【规则3.5-2】 长表达式要在低优先级操作符处拆分成新行,操作符放在新行之首(以便突出操作符),拆分出的新行要进行适当的缩进,使排版整齐,语句可读。if (very_longer_variable1 = very_longer
copyright@ 2008-2022 冰豆网网站版权所有
经营许可证编号:鄂ICP备2022015515号-1