软件开发规范v1.0

开发规范文档版本1.0Page2of25修订历史记录日期版本说明作者2013-1-211.0初稿linsmPage3of25目录1.前言61.1目的61.2概述62.命名规范(NamingConventions)62.1包命名72.2类命名72.3接口命名82.4方法命名82.5类成员参数82.6局部变量92.7常量92.8集合92.9魔法数字92.10其他102.11项目分层103.代码排版规范12Page4of253.1空行123.2空格123.3大括号(Braces)133.4换行(NewLines)133.5长度(Length)134.声明134.1类、接口134.2方法144.3字段145.其他约束155.1类成员可见性155.2赋值(Assignment)155.3165.4条件表达式使用165.5无效语句165.6Import规范175.7String比较17Page5of255.8注释要求175.9Tryif嵌套层次和分支复杂度195.10Switch语句196.设计规范196.1类与接口206.2方法206.3表达式与语句216.4控制语句226.5循环语句236.6异常处理24Page6of25软件开发规范文档1.前言1.1目的本规范的目的是使本组织能以标准的、规范的方式设计和编码。通过建立编码规范，以使每个开发人员养成良好的编码风格和习惯；并以此形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。1.2概述对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使自己和其他的程序员能够很容易地理解代码所执行的功能等。然而，在实际开发中，每个程序员所写的代码却经常自成一套，很少统一，导致理解困难，影响团队的开发效率及系统的质量等。因此，一份完整并被严格执行的开发规范是非常必须的，特别是对软件公司的开发团队而言。最根本的原则：代码虽然是给机器运行的，但却是给人读的！2.命名规范(NamingConventions)命名规范使程序更易读，从而更易于理解。它们也可以提供一些有关标识符功能的信息，以助于理解代码，例如，不论它是一个常量，包，还是类。大家遵守一定的规范，相互看其他人的代码也会更加方便。使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。例如，采用类似firstName，listAllUsers或CorporateCustomer这样的名字，尽量不使用汉语拼音及不相关单词命名，严禁使用汉语拼音首字母组合命名，虽然Java支持Page7of25Unicode命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。采用该领域的术语。如果用户称他们的“客户”(clients)为“顾客”(customers)，那么就采用术语Customer来命名这个类，而不用Client。采用大小写混合，提高名字的可读性。一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。包名全部小写。避免使用长名字（最好不超过25个字母）。避免使用相似或者仅在大小写上有区别的名字。避免使用数字，但可用2代替to，用4代替for等，如：go2Jsp。2.1包命名包名一般以项目或模块名命名，少用缩写和长名，一律小写，正则表达式为：^[a-z]+(\.[a-zA-Z_][a-zA-Z0-9_]*)*$。包名按如下规则组成：[基本包].[项目名].[模块名].[子模块名]..OA项目的包命名前三级为：com.well.oa。不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。2.2类命名类名采用大小写混合的方式，每个单词的首字母大写。尽量使你的类名简洁而富于描述。使用完整单词，避免缩写词(除非该缩写词被更广泛使用，像URL，HTML)。一般采用名词。Page8of252.3接口命名大小写规则与类名相似。接口可带I前缀或able、ible、er等后缀。2.4方法命名方法名是一个动名结构，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。正则表达式为：^[a-z][a-zA-Z0-9]*$类中常用方法的命名：1.类的获取方法（一般具有返回值）一般要求在被访问的字段名前加上get，如getFirstName()，getLastName()。2.类的设置方法（一般返回类型为void）：被访问字段名的前面加上前缀set，如setFirstName(),setLastName().3.类的布尔型的判断方法一般要求方法名使用单词is做前缀，如isPersistent()isString()。或者使用具有逻辑意义的单词，例如equal或equals。4.类的普通方法一般采用完整的英文描述说明成员方法功能，第一个单词尽可能采用动词，首字母小写，如openFile（），addCount（）。5.构造方法应该用递增的方式写。（参数多的写在后面）。6.toString()方法：一般情况下，每个类都应该定义toString(),其格式为：publicStringtoString(){…}。2.5类成员参数和类命名一样，但是首字母小写。参数命名和类成员命名一致。Page9of25'^[a-z][a-zA-Z0-9]*$'2.6局部变量局部变量名不应以下划线或美元符号开头，这个是java命名的惯例。局部变量建议全部使用小写。除了局部变量名外，所有实例，包括类，类常量，均采用大小写混合的方式。变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量（往往用在for循环中），临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型。正则表达式为：^[a-z][a-z0-9]*$2.7常量类常量和ANSI常量(static,final字段)的声明，应该全部大写，单词间用下划线隔开。(尽量避免ANSI常量，容易引起错误)。正则表达式为：^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$2.8集合集合，例如数组和列表，命名应采用完整的英文描述符，适当使用集合缩写后缀。如：ListproductList=newList();//产品列表ArrayuserArray=newArray();//用户列表2.9魔法数字不允许使用魔法数字，可以定义为常量使用。在程序里经常会用到一些量，它是有特定的含义的。例如，现在我们写一个薪金统计程序，公司员工有50人，我们在程序里就会用50这个数去进行各种各样的运算。在这里，50就是神秘的数。当别的程序员在程序里看到50这个数，将很难知道它的含义，造成Page10of25理解上的困难。在程序里出现神秘的数会降低程序的可读性、可维护性和可扩展性，故规定不得出现此类魔法数字。避免的方法是把神秘的数定义为一个常量。注意这个常量的命名应该能表达该数的意义，并且应该全部大写，以与对应于变量的标识符区别开来。例如上面50这个数，我们可以定义为一个名为NUM_OF_EMPLOYEES的常量来代替。这样，别的程序员在读程序的时候就可以容易理解了。2.10其他命名时应使用复数来表示它们代表多值（数组）。如：orderItems。2.11项目分层1、实体类实体类使用规范1、表名以所在模块的简写为前缀；2、实休类只作为一个JavaBean对象3、类的字段不可使用int、short、long、char、double、float、boolean和byte等基本数据类型，要使用基本数据类型对应的包装类Integer、Short、Long、Character、Double、Float、Boolean和Byte等可用工具类com.wellsoft.pt.utils.bean.PrimitiveTypeWrapperUtils对其属性赋初始值2、DAO数据访问DAO层实现类命名规范以Dao结束，如UserDao3、Service服务Page11of25Service服务层接口命名规范以Service结束，如UserService实现类命名规范以ServiceImpl结束，如UserServiceImpl4、Web控制器web层控件器命名规范以Controller结束，如UserController5、JSP页面展示jsp文件命名规范统一使用小写字母，若有多个单词用下划线_分开，一般以动词结束，如user_list.jsp列表user_view.jsp查看user_edit.jsp编辑user_maintain.jsp维护user_new.jsp新增6、值对象数据从页面收集到后台控制器的值对象命名规范1、值对象以Bean为结尾，如UserBean，收集后再用工具类com.wellsoft.pt.utils.bean.BeanUtils转换为实体类User2、直接使用实体类如User作为值对象收集页面数据Page12of253.代码排版规范排版主要为了界面规范，一方面为了代码清晰，另外可以方便进行代码合并时减少因排版引起不一致。在eclipse中可以使用固定排版模板，完成一致的排版样式。所有项目开发人员必须引入统一的排版模板。主要包括缩进，空格，空行，大括号，换行，长度等方面。3.1空行空行往往使用在如下方面。1)包的声明之后2)Import声明之前和之后3)Import组之间4)类声明之间5)类成员变量和方法声明之前6)在同一类型声明之前7)对于已存在的空行会整理成一行对于特别需要分开的行也可以添加空行，往往是为了逻辑划分。3.2空格1)逗号后面一律加空格2)类和匿名类的左大括号之前加空格3)方法和构造函数的左大括号之前加空格4)可变个数的参数的冒号后面加空格voidformat(Strings,Object...args){}5)标识符（label）后面的冒号后要加空格,目前不推荐使用标识符:Page13of256)注释类型@前面和左大括号之前加空格。3.3大括号(Braces)1)左大括号一律与它所从属的类,接口和关键字处于同一行2)左大括号一律与它所从属的方法和构造函数处于同一行3)左大括号一律与它所从属的枚举声明和枚举常量处于同一行4)左大括号一律与它所从属的注释类型声明处于同一行5)数组初始化中左大括号一律与声明处于同一行:6）所有区域都要使用大括号，例如if语句中只有一条语句也要用大括号括起来。3.4换行(NewLines)1)局域变量(localvariables)和成员不与其注释在同一行，不许使用与代码同行的注释，注释往往放在其注释内容上。2)一行最长为120个字符。3)同一行不能有多个声明，声明放置到新行中3.5长度(Length)1)文件长度不超过1000行，建议。2)方法长度不超过200行，建议。4.声明声明的基本原则是遵守Java语言规范，并遵从习惯用法。4.1类、接口声明定义：[可见性][('abstract'|'final')][Class|Interface]class_namePage14of25[('extends'|'implements')][父类或接口名]如：publicclassLoginActionextendsBaseActionimplemnetsActionListener方法良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：尽量限制成员函数的可见性。如果成员函数没必要公有(public)，就定义为保护(protected)；没必要保护。4.2方法声明定义：[可见性][('abstract'|'final')]['synchronized'][返回值类型]method_name(参数列表)[('throws')][异常列表]如：publicListlistAllUsers()throwsDAOException若有toString(),equals(),hashCode(),colone