软件开发规范v1.0.docx

开发规范文档版本 修订历史记录日期版本说明作者初稿linsm目录1.前言51.1目的51.2概述52.命名规范(Naming Conventions)52.1包命名62.2类命名62.3接口命名62.4方法命名62.5类成员 参数72.6局部变量72.7常量72.8集合72.9魔法数字72.10其他82.11项目分层83.代码排版规范93.1空行93.2空格93.3大括号(Braces)103.4换行(New Lines)103.5长度(Length)104.声明104.1类、接口104.2方法104.3字段115.其他约束115.1类成员可见性115.2赋值(Assignment)115.3125.4条件表达式使用125.5无效语句125.6Import 规范125.7String比较135.8注释要求135.9Try if嵌套层次和分支复杂度145.10Switch 语句146.设计规范156.1类与接口156.2方法156.3表达式与语句166.4控制语句166.5循环语句176.6异常处理18软件开发规范文档 1. 前言1.1 目的本规范的目的是使本组织能以标准的、规范的方式设计和编码。通过建立编码规范，以使每个开发人员养成良好的编码风格和习惯；并以此形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。1.2 概述对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使自己和其他的程序员能够很容易地理解代码所执行的功能等。然而，在实际开发中，每个程序员所写的代码却经常自成一套，很少统一，导致理解困难，影响团队的开发效率及系统的质量等。因此，一份完整并被严格执行的开发规范是非常必须的，特别是对软件公司的开发团队而言。最根本的原则：代码虽然是给机器运行的，但却是给人读的！2. 命名规范(Naming Conventions)命名规范使程序更易读，从而更易于理解。它们也可以提供一些有关标识符功能的信息，以助于理解代码，例如，不论它是一个常量，包，还是类。大家遵守一定的规范，相互看其他人的代码也会更加方便。 使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。例如，采用类似firstName，listAllUsers 或CorporateCustomer 这样的名字，尽量不使用汉语拼音及不相关单词命名，严禁使用汉语拼音首字母组合命名，虽然Java 支持Unicode 命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。 采用该领域的术语。如果用户称他们的“客户” (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)。一般采用名词。2.3 接口命名大小写规则与类名相似。接口可带I 前缀或able、ible、er 等后缀。2.4 方法命名方法名是一个动名结构，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。正则表达式为：a-za-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(),其格式为：public String toString()。2.5 类成员 参数和类命名一样，但是首字母小写。参数命名和类成员命名一致。a-za-zA-Z0-9*$2.6 局部变量 局部变量名不应以下划线或美元符号开头，这个是java命名的惯例。局部变量建议全部使用小写。除了局部变量名外，所有实例，包括类，类常量，均采用大小写混合的方式。变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量（往往用在for循环中），临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型。正则表达式为：a-za-z0-9*$2.7 常量类常量和ANSI常量(static , final 字段)的声明，应该全部大写，单词间用下划线隔开。(尽量避免ANSI常量，容易引起错误)。正则表达式为：A-ZA-Z0-9*(_A-Z0-9+)*$2.8 集合集合，例如数组和列表，命名应采用完整的英文描述符，适当使用集合缩写后缀。如：List productList = new List(); /产品列表Array userArray = new Array(); /用户列表2.9 魔法数字不允许使用魔法数字，可以定义为常量使用。在程序里经常会用到一些量，它是有特定的含义的。例如，现在我们写一个薪金统计程序，公司员工有50 人，我们在程序里就会用50 这个数去进行各种各样的运算。在这里，50 就是神秘的数。当别的程序员在程序里看到50 这个数，将很难知道它的含义，造成理解上的困难。在程序里出现神秘的数会降低程序的可读性、可维护性和可扩展性，故规定不得出现此类魔法数字。避免的方法是把神秘的数定义为一个常量。注意这个常量的命名应该能表达该数的意义，并且应该全部大写，以与对应于变量的标识符区别开来。例如上面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服务Service服务层接口命名规范以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作为值对象收集页面数据3. 代码排版规范排版主要为了界面规范，一方面为了代码清晰，另外可以方便进行代码合并时减少因排版引起不一致。在eclipse中可以使用固定排版模板，完成一致的排版样式。所有项目开发人员必须引入统一的排版模板。主要包括缩进，空格，空行，大括号，换行，长度等方面。3.1 空行空行往往使用在如下方面。1) 包的声明之后2) Import声明之前和之后3) Import组之间4) 类声明之间5) 类成员变量和方法声明之前6) 在同一类型声明之前7) 对于已存在的空行会整理成一行对于特别需要分开的行也可以添加空行，往往是为了逻辑划分。3.2 空格1) 逗号后面一律加空格2) 类和匿名类的左大括号之前加空格3) 方法和构造函数的左大括号之前加空格4) 可变个数的参数的冒号后面加空格void format(String s, Object. args) 5) 标识符（label）后面的冒号后要加空格,目前不推荐使用标识符:6) 注释类型前面和左大括号之前加空格。3.3 大括号(Braces)1) 左大括号一律与它所从属的类,接口和关键字处于同一行2) 左大括号一律与它所从属的方法和构造函数处于同一行3) 左大括号一律与它所从属的枚举声明和枚举常量处于同一行4) 左大括号一律与它所从属的注释类型声明处于同一行5) 数组初始化中左大括号一律与声明处于同一行:6） 所有区域都要使用大括号，例如 if语句中只有一条语句也要用大括号括起来。3.4 换行(New Lines)1) 局域变量(local variables)和成员不与其注释在同一行，不许使用与代码同行的注释，注释往往放在其注释内容上。2) 一行最长为120个字符。3) 同一行不能有多个声明，声明放置到新行中3.5 长度(Length)1) 文件长度不超过1000行，建议。2) 方法长度不超过200行，建议。4. 声明声明的基本原则是遵守Java 语言规范，并遵从习惯用法。4.1 类、接口声明定义：可见性(abstract|final) Class|Interface class_name(extends|implements)父类或接口名如：public class LoginAction extends BaseAction implemnets ActionListener方法良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：尽量限制成员函数的可见性。如果成员函数没必要公有(public)，就定义为保护(protected)；没必要保护。4.2 方法声明定义：可见性(abstract|final) synchronized返回值类型 method_name(参数列表)(throws)异常列表如：public List listAllUsers() throws DAOException若有toString(),equals(),hashCode(),colone()等重载自Object 的方法，应将其放在类的最后。声明顺序：构造方法，静态公共方法，公共方法，静态私有方法，受保护方法，私有方法，继承自Object 的方法4.3 字段字段定义语法规范：(public|private|protected)(final|volatile)statictransientdata_type field_name = expression ;若没有足够理由，不要把实例或类变量声明为公有。公共和保护的可见性应当尽量避免，所有的字段都建议置为私有，由获取和设置成员函数（Getter、Setter）访问。不允许“隐藏”字段，即给局部变量所取的名字，不可与另一个更大范围内定义的字段的名字相同（或相似）。例如，如果把一个字段叫做firstName ，就不要再生成一个局部变量叫做firstName，或者任何易混肴的名字，如fistName。数组声明时当将跟在类型后，而不是字段名后，如：Integer ai = new Integer2; /一个整数对象数组，用于.Integer aj = new Integer3; /不要用这种数组声明方式一行代码只声明一个变量，仅将一个变量用于一件事。声明顺序：常量，类成员变量，实例变量，公有字段，受保护字段，私有字段。5. 其他约束5.1 类成员可见性说明：检查类成员的可见性。只有static final 成员是public的，其他的类成员都是private的.5.2 赋值(Assignment)1 不允许内部赋值,如:String s = Integer.toString(i = 2);2 不允许更改的循环控制变量比如，一个for循环的循环数是只应该在最后的 i+ 中更改的，如果出现以下代码：for (int i = 0; i 1; i+) i+; / 这里是极可能是程序员大意写出来的。 3 参数赋值对方法的参数赋值一般说来，是不好的编程技巧。而强制开发人员声明一个final 参数，也不够友好。public void test1(int a) a = 1; /checkstyle报检查错误 5.3函数的参数个数不超过5个，若需要传递多个参数时，当使用一个容纳这些参数的对象进行传递，以提高程序的可读性和可扩展性，还可以考虑使用动态参数。5.4 条件表达式使用1 简化的条件表达式，检查过度复杂的条件表达式，比如： (b = true), b | true, !false, 难读且容易出错。这里最好简化使用。5.5 无效语句说明： 检查无效语句（单独;语句）.public void test4() if(true); /if语句后的;号引起checkstyle检查错误 doConditionalStuff(); doUnconditionalStuff(); 5.6 Import 规范避免引用未使用的import检查.以下几种import是没用/没意义的：没有被用到，重复的，import java.lang的，import 与该类在同一个package的。另外不要引入“.*”的包，会有性能问题。5.7 String比较检查进行字符串比较时，不能用=或者!=，应该用equals。另外需要先检查一个可能为null的字符串是否在equals()比较的左边，避免空指针异常。5.8 注释要求1）项目需要导入统一的注释模板。需要添加javadoc注释的地方包括：所有的非私有变量，所有的public，protected非私有方法，类和接口。 注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员理解。 如果你的程序不值得注释，那么它很可能也不值得运行。 避免使用装饰性内容。 保持注释的简洁。 注释信息不仅要包括代码的功能，还应给出原因。 不要为注释而注释。 除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。2) 编写Java类/接口时，在类/接口、非私有方法、非私有变量的上一行用/*前导并回车可自动产生JavaDoc注释的格式，将%x%修改为实际的内容。3) 在非私有方法的JavaDoc注释的补充说明一般有参数有返回值有异常的方法自动生成的注释类似如下（不包括红色字体的内容）：/* * * %方法的一句话概述（注：句号不能删除，本注应删除）%。 * %方法详述（简单方法可不必详述）% * param s 说明参数含义 * return 说明返回值含义 * throws IOException 说明发生此异常的条件 * throws NullPointerException 说明发生此异常的条件 */默认生成的JavaDoc注释没有这些红色字体的内容，它们必须被填入实际内容，才能产生优美格式的JavaDoc文档。4）以下情况必须添加注释： 私有方法，除构造函数外，可以添加该方法的注释（JavaDoc注释或非JavaDoc注释均可）。 复杂方法（如方法体超过30行），或包含关键算法的方法，必须对内部的操作步骤添加注释（行注释/或块注释/* */均可）。 方法内部多次转换含义的变量，必须对该变量的含义发生变化时添加注释。 方法内部存在不易理解的多个分支条件的表达式，必须对每个分支添加注释。以下情况可不必添加注释： PO类的属性（私有变量），由于已经在get/set方法内添加JavaDoc注释，因此可不必添加。5.9 Try if嵌套层次和分支复杂度try嵌套层数，最多2层，也就是两个try。If的嵌套层数，最多4层。确保函数的分支复杂度没有超出限制。该复杂度是通过考察大部分函数（构造函数，一般方法，静态初始函数，实例初始化函数） 中的 if, while, do, for, ? : , catch, switch, case 语句和 &, |的操作符的数目来计算得到的。它表示了通过一个函数的最少分支数，也因此体现了需要进行的测试数目。一般而言1-4 是优秀，5-7是合格。8-10看情况重构。11个以上一定要马上重构。5.10 Switch 语句确保switch语句的default一定在最后出现。虽然java语法允许default可以放在switch中的任何位置，但是把它放在各个case的最下面是可读性最强的，如果不写default , 就会产生逻辑错误，却没有提示。6. 设计规范6.1 类与接口1.1）基本原则类的划分粒度，不可太大，造成过于庞大的单个类，也不可太细，从而使类的继承太深。一般而言，一个类只做一件事；另一个原则是根据每个类的职责进行划分，比如用User 来存放用户信息，而用UserDAO 来对用户信息进行数据访问操作（比如存取数据库），用UserService 来封装用户信息的业务操作等等。多个类中使用相同方法时将其方法提到一个接口中或使用抽象类，尽量提高重用度。将不希望再被继承的类声明成final，例如某些实用类，但不要滥用final，否则会对系统的可扩展性造成影响。将不希望被实例化的类的缺省构造方法声明成private。2）抽象类与接口一般而言：接口定义行为，而抽象类定义属性和公有行为，注意两者间的取舍，在设计中，可由接口定义公用的行为，由一个抽象类来实现其部分或全部方法，以给子类提供统一的行为定义，可参考Java 集合等实现。多使用接口，尽量做到面向接口的设计，以提高系统的可扩展性。3）继承与组合尽量使用组合来代替继承，一则可以使类的层次不至于过深，而且会使类与类，包与包之间的耦合度更小，更具可扩展性。尽量避免在深度继承的类的构造函数中建立对象。6.2 方法2.1）基本原则一个方法只完成一项功能，在定义系统的公用接口方法外的方法应尽可能的缩小其可见性。避免用一个类实例去访问其静态变量和方法。避免在一个较长的方法里提供多个出口：/不要使用这钟方式，当处理程序段很长时将很难找到出口点if(condition)return A;elsereturn B;/ 建议使用如下方式String result = null;if(condition)result = A;elseresult = B;return result;6.3 表达式与语句3.表达式和语句当清晰、简洁，易于阅读和理解，避免使用晦涩难懂的语句。每行至多包含一条执行语句，过长当换行。避免在构造方法中执行大量耗时的初始化工作，应当将这中工作延迟到被使用时再创建相应资源，如果不可避免，则当使用对象池和Cache 等技术提高系统性能。尽量在声明局部变量的同时初始化。唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。一般而言，在含有多种运算符的表达式中使用圆括号来避免运算符优先级问题，是个好方法。即使运算符的优先级对你而言可能很清楚，但对其他人未必如此。你不能假设别的程序员和你一样清楚运算符的优先级。不要为了表现编程技巧而过分使用技巧，简单就好。6.4 控制语句判断中如有常量，则应将常量置于判断式的右侧。如：if ( true = isAdmin().尽量不使用三目条件的嵌套。所有if 语句必须用包括起来,即便是只有一句：if (true)/do something.if (true)i = 0; /不要使用这种当有多个else 分句时当分别注明其条件，注意缩进并对齐，如：/先判断i 是否等于1if (i = 1)/if_1/./然后判断i = 2else if (i = 2)/i = 2 说明。j = i;/如果都不是(i 2 | i 1)else/说明出错了/./end if_1过多的else 分句请将其转成switch 语句或使用子函数。每当一个case 顺着往下执行时(因为没有break 语句)，通常应在break 语句的位置添加注释。如：switch (condition) case ABC:/ statements;/ 继续下一个CASEcase DEF:/ statements;break;case XYZ:/ statements;break;default:/ statements;break;/ end switch6.5 循环语句循环中必须有终止循环的条件或语句，避免死循环。当在for 语句的初始化或更新子句中使用逗号时，避免因使用三个以上变量，而导致复杂度提高。若需要，可以在for 循环之前(为初始化子句)或for 循环末尾(为更新子句)使用单独的语句。因为循环条件在每次循环中多会执行一次，故尽量避免在其中调用耗时或费资源的操作，比较一下两种循环的