CMMI- 软件开发代码编程规范.docx

广东技术股份有限公司编程规范文件编号文件状态草稿正式发布正在修改当前版本拟制张三日期年月日审核李四日期年月日批准王五日期年月日发布日期年月日生效日期年月日广东技术股份有限公司广东技术股份有限公司修订历史记录增加修订删除变更版本号日期变更类型修改人摘要备注建立编程规范广东技术股份有限公司目录目的使用范围编程规范文件结构程序的版式命名规则缩进规则编程规范代码组织与风格注解命名声明表达式和语句错误处理和异常事件可移植性复用广东技术股份有限公司目的定义组织的编程规范以提高程序的可读性可靠性使用范围适合于公司采用编程语言开发的所有软件项目编程规范文件结构每个程序通常分为两个文件一个文件用于保存程序的声明称为头文件另一个文件用于保存程序的实现称为定义文件程序的头文件以为后缀程序的定义文件以为后缀程序的定义文件通常以为后缀也有一些系统以或为后缀这里以平台为准版权和版本的声明版权和版本的声明位于头文件和定义文件的开头参见示例主要内容有版权信息文件名称标识符摘要当前版本号作者修改者完成日期版本历史信息说明一项描述本文件的内容功能内部各部分之间的关系及本文件与其它文件关系等是修改历史记录列表每条修改记录应包括修改日期修改者及修改内容简述示例示例版本和版权的声明广东技术股份有限公司广东技术股份有限公司头文件的结构头文件由三部分内容组成头文件开头处的版权和版本声明参见示例预处理块函数和类结构声明等假设头文件名称为头文件的结构参见示例规则为了防止头文件被重复引用应当用结构产生预处理块规则用格式来引用标准库的头文件编译器将从标准示例定义文件的结构示例版本和版权的声明广东技术股份有限公司库目录开始搜索规则用格式来引用非标准库的头文件编译器将从用户的目录开始搜索建议头文件中只存放声明而不存放定义在语法中类的成员函数可以在声明的同时被定义并且自动成为内联函数这虽然会带来书写上的方便但却造成了风格不一致弊大于利建议将成员函数的定义与声明分开不论该函数体有多么小建议不提倡使用全局变量尽量不要在头文件中出现象这类声明定义文件的结构定义文件有三部分内容定义文件开头处的版权和版本声明参见示例对一些头文件的引用程序的实现体包括数据和代码假设定义文件的名称为定义文件的结构参见示例头文件的作用早期的编程语言如没有头文件的概念语言的初学者虽然会用使用头文件但常常不明其理这里对头文件的作用略作解释通过头文件来调用库功能在很多场合源代码不便或不准向用户公布只要向用户提供头文件和二进制的库即可用户只需要按照头文件中的接口声明来调用库功能而不必关心接口怎么实现的编译器会从库中提取相应的代码头文件能加强类型安全检查如果某个接口被实现或被使用时其方式与头文件中的声明不一致编译器就会指出错误这一简单的规则能大大减轻程序员调试改错的负担目录结构如果一个软件的头文件数目比较多如超过十个通常应将头文件和定义文件分别保存于不同的目录以便于维护例如可将头文件保存于目录将定义文件保存于目录可以是多级目录如果某些头文件是私有的它不会被用户的程序直接引用则没有必要公开其声明为了加强信息隐藏这些私有的头文件可以和定义文件存放于同一个目录程序的版式版式虽然不会影响程序的功能但会影响可读性程序的版式追求清晰美观是程序风格的重要构成因素广东技术股份有限公司可以把程序的版式比喻为书法好的书法可让人对程序一目了然看得兴致勃勃差的程序书法如螃蟹爬行让人看得索然无味更令维护者烦恼有加请程序员们学习程序的书法弥补大学计算机教育的漏洞实在很有必要空行空行起着分隔程序段落的作用空行得体不过多也不过少将使程序的布局更加清晰空行不会浪费内存虽然打印含有空行的程序是会多消耗一些纸张但是值得所以不要舍不得用空行规则在每个类声明之后每个函数定义结束之后都要加空行参见示例规则在一个函数体内逻揖上密切相关的语句之间不加空行其它地方应加空行分隔参见示例广东技术股份有限公司代码行规则一行代码只做一件事情如只定义一个变量或只写一条语句这样的代码容易阅读并且方便于写注释规则等语句自占一行执行语句不得紧跟其后不论执行语句有多少都要加这样可以防止书写失误建议尽可能在定义变量的同时初始化该变量就近原则如果变量的引用处和其定义处相隔比较远变量的初始化很容易被忘记如果引用了未被初始化的变量可能会导致程序错误本建议可以减少隐患例如定义并初绐化定义并初绐化定义并初绐化示例为风格良好的代码行示例为风格不良的代码行宽度高度深度宽度高度深度空行代码行内的空格规则关键字之后要留空格象等关键字之后至少要留一个空格否则无法辨析关键字象等关键字之后应留一个空格再跟左括号以突出关键字规则函数名之后不要留空格紧跟左括号以与关键字区别规则向后紧跟向前紧跟紧跟处不留空格规则之后要留空格如如果不是一行的结束符号其后要留空格如规则赋值操作符比较操作符算术操作符逻辑操作符位域操作符如等二元操作示例风格良好的代码行示例风格不良的代码行广东技术股份有限公司符的前后应当加空格规则一元操作符如地址运算符等前后不加空格规则象这类操作符前后不加空格建议对于表达式比较长的语句和语句为了紧凑起见可以适当地去掉一些空格如和良好的风格不良的风格良好的风格不良的风格良好的风格不良的风格良好的风格不良的风格过多的空格良好的风格不好的风格良好的风格不良的风格不要写成不要写成不要写成对齐规则程序的分界符和应独占一行并且位于同一列同时与引用它们的语句左对齐规则之内的代码块在右边数格处左对齐示例为风格良好的对齐示例为风格不良的对齐示例代码行内的空格广东技术股份有限公司如果出现嵌套的则使用缩进对齐如长行拆分规则代码行最大长度宜控制在至个字符以内代码行不要过长否则眼睛看不过来也不便于打印规则长表达式要在低优先级操作符处拆分成新行操作符放在新行之首以便突出操作符拆分出的新行要进行适当的缩进使排版整齐语句可读修饰符的位置修饰符和应该靠近数据类型还是该靠近变量名是个有争议的话题若将修饰符靠近数据类型例如从语义上讲此写法比较直观即是类型的指针上述写法的弊端是容易引起误解例如此处容易被误解为指针变量虽然将和分行定义可以避免误解但并不是人人都愿意这样做规则应当将修饰符和紧靠变量名例如此处不会被误解为指针注释注释的原则是有助于对程序的阅读理解在该加的地方都加了注释不宜太多也不能太少注释语言必须准确易懂简洁一般情况下源程序有效注释量必须在以上语言的注释符为语言中程序块的注释常采用行注释一般示例风格良好的对齐示例风格不良的对齐示例长行的拆分广东技术股份有限公司采用注释通常用于版本版权声明函数接口说明重要的代码行或段落提示虽然注释有助于理解代码但注意不可过多地使用注释参见示例函数介绍输入参数输出参数返回值规则注释是对代码的提示而不是文档程序中的注释不可喧宾夺主注释太多了会让人眼花缭乱注释的花样要少规则如果代码本来就是清楚的则不必加注释否则多此一举令人厌烦例如加多余的注释规则边写代码边注释修改代码同时修改相应的注释以保证注释与代码的一致性不再有用的注释要删除规则注释应当准确易懂防止注释有二义性错误的注释不但无益反而有害规则尽量避免在注释中使用缩写特别是不常用缩写规则注释的位置应与被描述的代码相邻可以放在代码的上方或右方不可放在下方规则当代码比较长特别是有多重嵌套时应当在一些段落的结束处加注释便于阅读类的版式类可以将数据和函数封装在一起其中函数表示了类的行为或称服务类提供关键字和分别用于声明哪些数据和函数是公有的受保护的或者是私有的这样可以达到信息隐藏的目的即让类仅仅公开必须要让外界知道的内容而隐藏其它一切内容我们不可以滥用类的封装功能不要把它当成火锅什么东西都往里扔类的版式主要有两种方式将类型的数据写在前面而将类型的函数写在后面如示例采用这种版式的程序员主张类的设计以数据为中心重点关注类的内部结构示例程序的注释广东技术股份有限公司将类型的函数写在前面而将类型的数据写在后面如示例采用这种版式的程序员主张类的设计以行为为中心重点关注的是类应该提供什么样的接口或服务很多教课书受到第一本著作的影响不知不觉地采用了以数据为中心的书写方式并不见得有多少道理建议采用以行为为中心的书写方式即首先考虑类应该提供什么样的函数这是很多人的经验这样做不仅让自己在设计类时思路清晰而且方便别人阅读因为用户最关心的是接口谁愿意先看到一堆私有数据成员命名规则比较著名的命名规则当推公司的匈牙利法该命名规则的主要思想是在变量和函数名中加入前缀以增进人们对程序的理解例如所有的字符变量均以为前缀若是指针变量则追加前缀如果一个变量由开头则表明它是指向字符指针的指针匈牙利法最大的缺点是烦琐例如倘若采用匈牙利命名规则则应当写成前缀表示类型前缀表示类型如此烦琐的程序会让绝大多数程序员无法忍受据考察没有一种命名规则可以让所有的程序员赞同程序设计教科书一般都不指定命名规则命名规则对软件产品而言并不是成败悠关的事我们不要化太多精力试图发明世界上最好的命名规则而应当制定一种令大多数项目成员满意的命名规则并在项目中贯彻实施共性规则本节论述的共性规则是被大多数程序员采纳的我们应当在遵循这些共性规则的前提下再扩充特定的规则如节规则标识符应当直观且可以拼读可望文知意不必进行解码示例以数据为中心版式示例以行为为中心的版式广东技术股份有限公司标识符最好采用英文单词或其组合便于记忆和阅读切忌使用汉语拼音来命名程序中的英文单词一般不会太复杂用词应当准确例如不要把写成规则标识符的长度应当符合原则几十年前老规定名字不准超过个字符现今的不再有此限制一般来说长名字能更好地表达含义所以函数名变量名类名长达十几个字符不足为怪那么名字是否越长约好不见得例如变量名就比好用单字符的名字也是有用的常见的如等它们通常可用作函数内的局部变量规则命名规则尽量与所采用的操作系统或开发工具的风格保持一致例如应用程序的标识符通常采用大小写混排的方式如而应用程序的标识符通常采用小写加下划线的方式如别把这两类风格混在一起用规则类的命名应该尽量清楚的反应它所表示的客观事物例如员工类账户类规则程序中不要出现仅靠大小写区分的相似的标识符例如变量与容易混淆函数与容易混淆规则程序中不要出现标识符完全相同的局部变量和全局变量尽管两者的作用域不同而不会发生语法错误但会使人误解规则变量的名字应当使用名词或者形容词名词例如规则全局函数的名字应当使用动词或者动词名词动宾词组例如全局函数类的成员函数规则用正确的反义词组命名具有互斥意义的变量或相反动作的函数等例如建议尽量避免名字中出现数字编号如等除非逻辑上的确需要编号这是为了防止程序员偷懒不肯为命名动脑筋而导致产生无意义的名字因为广东技术股份有限公司用数字编号最省事简单的应用程序命名规则本文对匈牙利命名规则做了合理的简化下述的命名规则简单易用比较适合于应用软件的开发规则类名和函数名用大写字母开头的单词组合而成例如类名类名函数名函数名规则变量和参数用小写字母开头的单词组合而成例如规则常量全用大写的字母用下划线分割单词例如规则静态变量加前缀表示例如静态变量规则如果不得已需要全局变量则使全局变量加前缀表示例如全局变量全局变量规则类的数据成员加前缀表示这样可以避免数据成员与成员函数的参数同名例如规则类的数据成员加前缀表示变量是一个类型的句柄例如控件命名规则广东技术股份有限公司分类前缀类控件类型单元容器窗体面板按钮下拉式列表框图片按钮快速按钮文本输入选择标签文本输入框控件控件列表框图像图片框图片列表图表菜单主菜单菜单项弹出菜单工具栏工具栏工具条按钮网格网格第三方控件布局信息组织列表显示控件树型结构显示控件分页选项卡分隔条滚动条状态栏缩进规则广东技术股份有限公司在各个编译环境中把键的长度改为个空格长大括号单独占一行但是不缩进语句的缩进风格查询列表的书写风格与注释综合考虑一行有多列超过个字符时基于列对齐原则采用下行缩进子句的书写规范每个条件占一行嵌套查询条件书写规范控制结构的缩进程序应以缩进形式展现程序的块结构和控制结构下列保留字的下一行缩进四格下列保留字所在行前移四格缩进的限制每次缩进标准为个空格可使用键任何一个程序最大行宽不得超过列第一行续行语句缩进四格后续续行语句与第一行续行语句对齐长语句的下一语句以长语句为对齐基准参照上面规定执行广东技术股份有限公司编程规范代码组织与风格缩进代码中以缩进长度单个函数长度不应大于行不包括注释行超过时应当考虑使用子函数行宽程序最大行宽一般不超过列超过者应折行书写因编译器工具兼容问题可以不折行间隔类方法等之间应以空行相隔以增加可读性风格对每个文件类接口方法等都应有较详细的注释类接口方法的左括号换行并独占一行各控制条件循环的语句级别的左括号紧跟该代码段最后一句后不单独占行较长的方法以及类接口等的右括号后应使用标识其结束具体参考如下例文件包注释引用包注释类注释变量注释方法注释语句注释条件注释广东技术股份有限公司注解基本原则注释应该增加代码的清晰度代码注释的目的是要使代码更易于被同时参与程序设计的开发人员以及其他后继开发人员理解如果你的程序不值得注释那么它也很可能也不值得运行避免使用装饰性内容保持注释的简洁注释信息不仅要包括代码的功能还应给出原因尽量不使用行末注释文件包注解在每个文件包的头部都应该对该文件的功能作用作者版权以及修改记录等进行注解参考如下模板任务队列管理类管理任务队列完成该类的编码添加类接口注解在类接口定义之前当对其进行注释包括类接口的目的作用功能继承于何种父类实现的接口以及重大的修改记录等等基本依据标准的规范方法注解依据标准规范对方法进行注释以明确该方法功能作用各参数含义以及返回值等复杂的算法用在方法内注解出如广东技术股份有限公司语句结果集异常执行查询该方法调用的方法并返回结果集语句注解应对重要的变量加一注释以说明其含义等应对不易理解的分支条件表达式加注释不易理解的循环应说明出口条件过长的方法实现应将其语句按实现的功能分段加以概括性说明对于异常处理注明正常情况及异常情况或者条件并说明当异常发生时程序当如何处理单行语句注解应当比其注解的语句缩进两个字符注解参考表项目注释部分参数参数类型参数用来做什么任何约束或前提条件示例字段属性字段描述注释所有使用的不变量示例并行事件可见性决策类类的目的已知的问题类的开发维护历史版本注释出采用的不变量并行策略编译单元每一个类类内定义的接口含简单的说明文件名和或标识信息修改维护记录版权信息获取成员函数若可能说明为什么使用滞后初始化接口目的它应如何被使用以及如何不被使用局部变量用处目的成员函数注释成员函数做什么以及它为什么做这个哪些参数必须传递给一个成员函数成员函数返回什么已知的问题任何由某个成员函数抛出的异常可见性决策广东技术股份有限公司成员函数是如何改变对象的包含任何修改代码的历史如何在适当情况下调用成员函数的例子适用的前提条件和后置条件成员函数内部注释控制结构代码做了些什么以及为什么这样做局部变量难或复杂的代码或代码处理顺序包包的基本原理包中的类功能和用途包的开发修改维护版本信息版权信息命名基本原则使用可以准确说明变量字段类的完整的英文描述符例如采用类似或这样的名字采用该领域的术语如果用户称他们的客户为顾客那么就采用术语来命名这个类而不用采用大小写混合提高名字的可读性一般应该采用小写字母但是类和接口的名字的首字母以及任何中间单词的首字母应该大写尽量少用缩写避免使用长名字最好不超过个字母避免使用相似或者仅在大小写上有区别的名字字段常量采用完整的英文大写单词在词与词之间用下划线连接变量对不易清楚识别出该变量类型的变量应使用类型缩写作其前缀如字符串使用使用等等除第一各个单词外其余单词首字母大写命名时应使用复数来表示它们代表多值如组件部件应采用完整的英文描述符命名组件接口部件使用匈牙利命名法则如集合一个集合例如数组和矢量应采用复数命名来表示队列中存放的对象类型命名应采用完整的英文描述符名字中所有非开头的单词的第一个字母应大写适当使用集合缩写前缀如类接口应当所有单词首字母大写应当能间接而确切地反应该类接口的含义一般采用名词方法方法的命名应采用完整的英文描述符大小写混合使用所有中间单词的第一个字母大广东技术股份有限公司写方法名称的第一个单词常常采用一个有强烈动作色彩的动词取值类使用前缀设值类使用前缀判断类使用前缀例方法参数建议顺序被操作者操作内容操作标志其他例文件包文件名当与其类严格相同包名一律小写多单词以下划线连接基本包所有包文件都属于此包命名约定列表操作项命名约定示例参数使用传递值对象的完整的英文描述符字段属性字段采用完整的英文描述第一个字母小写任何中间单词的首字母大写布尔型的获取成员函数所有的布尔型获取函数必须用单词做前缀类采用完整的英文描述符所有单词的第一个字母大写编译单元文件使用类或接口的名字或者如果文件中除了主类之外还有多个类时加上前缀来说明它是一个源码文件部件组件使用完整的英文描述来说明组件的用途将组件类型使用匈牙利命名法则作其前缀构造函数使用类名析构函数没有析构函数但一个对象在垃圾收集时调用成员函数异常通常采用字母表示异常静态常量字段常量全部采用大写字母单词之间用下划线分隔采用静态常量获取成员函数获取成员函数被访问字段名的前面加上前缀接口采用完整的英文描述符说明接口封装所有单词的第一个字母大写使用前缀其后使用或者等后缀但这不是必需的局部变量采用完整的英文描述符第一个字母小写但不要隐藏已有字段例如如果有一个字段叫不要让一个局部变量叫循环计数器通常采用字母或者包采用完整的英文描述符所有单词都小写多个单词以下划线相连所有包都属于成员函数采用完整的英文描述说明成员函数功能第一个单词尽可能采用一个生动的动词除第一个单词外每个单词第一个字母小写广东技术股份有限公司设置成员函数被访问字段名的前面加上前缀声明包行要在行之前中标准的包名要在本地的包名之前而且按照字母顺序排列如果行中包含了同一个包中的不同子目录则应该用来处理在导入包时当完全限制代码所使用的类的名字而少用通配符的方式如在包名下空一行再写类接口开括号与闭括号各自独立成行并对齐并使用标识声明顺序建议私有字段公有受保护字段构造函数公共成员函数被保护成员函数私有成员函数尽力使类的公共和保护接口最小化在开始编写类的代码之前应先定义该类的公共接口字段公共和保护的可见性应当尽量避免所有的字段都应置为私有由获取和设置成员函数存取函数访问不允许隐藏字段即给局部变量参数或者字段所取的名字与另一个更大范围内定义的变量参数或者字段的名字相同或相似例如如果把一个字段叫做就不要再生成一个局部变量或者参数叫做或者任何类似的名字如或一行代码只声明一个变量仅将变量用于一件事方法广东技术股份有限公司良好的程序设计应该尽可能减小类与类之间耦合所遵循的经验法则是尽量限制成员函数的可见性如果成员函数没必要公有就定义为保护没必要保护就定义为私有表达式和语句各功能块间以空行相隔判断中如有常量则应将常量置与判断式的右侧如尽量不使用三目条件判断循环计数器如等需在循环体前声明避免使用如等语句循环跳转条件当注明清楚错误处理和异常事件通常的思想是只对错误采用异常处理逻辑和编程错误设置错误被破坏的数据资源耗尽等等通常的法则是系统在正常状态下以及无重载和硬件失效状态下不应产生任何异常最小化从一个给定的抽象类中导出的异常的个数对于经常发生的可预计事件不要采用异常不使用异常实现控制结构确保状态码有一个正确值在本地进行安全性检查而不是让用户去做可移植性为保证系统的跨平台性不得使用任何某平台专有用的资源类库等在代码级也必须同时保证系统的可移植性必须在下都进行测试并且保证处理结果的一致性复用任何可复用的代码资源等必须打成可重用包任何从外部源所购买复用的类库或者包应是纯粹的语言以确保所用的部件能在所有平台上工作