软件开发规范v.docx
《软件开发规范v.docx》由会员分享，可在线阅读，更多相关《软件开发规范v.docx（17页珍藏版）》请在冰豆网上搜索。
软件开发规范v
开发规范文档
版本<1.0>
修订历史记录
日期
版本
说明
作者
<2013-1-21>
<1.0>
初稿
linsm
1.前言5
1.1目的5
1.2概述5
2.命名规范（NamingConventions）5
2.1包命名6
2.2类命名6
2.3接口命名6
2.4方法命名6
2.5类成员参数7
2.6局部变量7
2.7常量7
2.8集合7
2.9魔法数字7
2.10其他8
2.11项目分层8
3.代码排版规范9
3.1空行9
3.2空格9
3.3大括号（Braces）10
3.4换行（NewLines）10
3.5长度（Length）10
4.声明10
4.1类、接口10
4.2方法10
4.3字段11
5.其他约束11
5.1类成员可见性11
5.2赋值（Assignment）11
5.312
5.4条件表达式使用12
5.5无效语句12
5.6Import规范12
5.7String比较13
5.8注释要求13
5.9Tryif嵌套层次和分支复杂度14
5.10Switch语句14
6.设计规范15
6.1类与接口15
6.2方法15
6.3表达式与语句16
6.4控制语句16
6.5循环语句17
6.6异常处理18
软件开发规范文档
1.前言
目的
本规范的目的是使本组织能以标准的、规范的方式设计和编码。
通过建立编码规范，以使每个开发人员养成良好的编码风格和习惯；并以此形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。
概述
对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使自己和其他的程序员能够很容易地理解代码所执行的功能等。
然而，在实际开发中，每个程序员所写的代码却经常自成一套，很少统一，导致理解困难，影响团队的开发效率及系统的质量等。
因此，一份完整并被严格执行的开发规范是非常必须的，特别是对软件公司的开发团队而言。
最根本的原则：
代码虽然是给机器运行的，但却是给人读的！
2.命名规范（NamingConventions）
命名规范使程序更易读，从而更易于理解。
它们也可以提供一些有关标识符功能的信息，以助于理解代码，例如，不论它是一个常量，包，还是类。
大家遵守一定的规范，相互看其他人的代码也会更加方便。
Ø使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。
例如，采用类似firstName，listAllUsers或CorporateCustomer这样的名字，尽量不使用汉语拼音及不相关单词命名，严禁使用汉语拼音首字母组合命名，虽然Java支持Unicode
命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。
Ø采用该领域的术语。
如果用户称他们的“客户”（clients）为“顾客”（customers），那么就采用术语Customer来命名这个类，而不用Client。
Ø采用大小写混合，提高名字的可读性。
一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。
包名全部小写。
Ø避免使用长名字（最好不超过25个字母）。
Ø避免使用相似或者仅在大小写上有区别的名字。
Ø避免使用数字，但可用2代替to，用4代替for等，如：
go2Jsp。
包命名
包名一般以项目或模块名命名，少用缩写和长名，一律小写，正则表达式为：
^[a-z]+（\.[a-zA-Z_][a-zA-Z0-9_]*）*$。
包名按如下规则组成：
[基本包].[项目名].[模块名].[子模块名]..
OA项目的包命名前三级为：
com.well.oa。
不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。
类命名
类名采用大小写混合的方式，每个单词的首字母大写。
尽量使你的类名简洁而富于描述。
使用完整单词，避免缩写词（除非该缩写词被更广泛使用，像URL，HTML）。
一般采用名词。
接口命名
大小写规则与类名相似。
接口可带I前缀或able、ible、er等后缀。
方法命名
方法名是一个动名结构，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。
正则表达式为：
^[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（）{…}。
类成员参数
和类命名一样，但是首字母小写。
参数命名和类成员命名一致。
'^[a-z][a-zA-Z0-9]*$'
局部变量
局部变量名不应以下划线或美元符号开头，这个是java命名的惯例。
局部变量建议全部使用小写。
除了局部变量名外，所有实例，包括类，类常量，均采用大小写混合的方式。
变量名应简短且富于描述。
变量名的选用应该易于记忆，即，能够指出其用途。
尽量避免单个字符的变量名，除非是一次性的临时变量（往往用在for循环中），临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型。
正则表达式为：
^[a-z][a-z0-9]*$
常量
类常量和ANSI常量（static,final字段）的声明，应该全部大写，单词间用下划线隔开。
（尽量避免ANSI常量，容易引起错误）。
正则表达式为：
^[A-Z][A-Z0-9]*（_[A-Z0-9]+）*$
集合
集合，例如数组和列表，命名应采用完整的英文描述符，适当使用集合缩写后缀。
如：
ListproductList=newList（）;//产品列表
ArrayuserArray=newArray（）;//用户列表
魔法数字
不允许使用魔法数字，可以定义为常量使用。
在程序里经常会用到一些量，它是有特定的含义的。
例如，现在我们写一个薪金统计程序，公司员工有50人，我们在程序里就会用50这个数去进行各种各样的运算。
在这里，50就是"神秘的数"。
当别的程序员在程序里看到50这个数，将很难知道它的含义，造成理解上的困难。
在程序里出现"神秘的数"会降低程序的可读性、可维护性和可扩展性，故规定不得出现此类"魔法数字"。
避免的方法是把神秘的数定义为一个常量。
注意这个常量的命名应该能表达该数的意义，并且应该全部大写，以与对应于变量的标识符区别开来。
例如上面50这个数，我们可以定义为一个名为NUM_OF_EMPLOYEES的常量来代替。
这样，别的程序员在读程序的时候就可以容易理解了。
其他
命名时应使用复数来表示它们代表多值（数组）。
如：
orderItems。
项目分层
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结束，如UserDao
3、Service服务
Service服务层接口命名规范
以Service结束，如UserService
实现类命名规范
以ServiceImpl结束，如UserServiceImpl
4、Web控制器
web层控件器命名规范
以Controller结束，如UserController
5、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转换为实体类User
2、直接使用实体类如User作为值对象收集页面数据
3.代码排版规范
排版主要为了界面规范，一方面为了代码清晰，另外可以方便进行代码合并时减少因排版引起不一致。
在eclipse中可以使用固定排版模板，完成一致的排版样式。
所有项目开发人员必须引入统一的排版模板。
主要包括缩进，空格，空行，大括号，换行，长度等方面。
空行
空行往往使用在如下方面。
1）包的声明之后
2）Import声明之前和之后
3）Import组之间
4）类声明之间
5）类成员变量和方法声明之前
6）在同一类型声明之前
7）对于已存在的空行会整理成一行
对于特别需要分开的行也可以添加空行，往往是为了逻辑划分。
空格
1）逗号后面一律加空格
2）类和匿名类的左大括号之前加空格
3）方法和构造函数的左大括号之前加空格
4）可变个数的参数的冒号后面加空格
voidformat（Strings,Object...args）{
}
5）标识符（label）后面的冒号后要加空格,目前不推荐使用标识符:
6）注释类型@前面和左大括号之前加空格。
大括号（Braces）
1）左大括号一律与它所从属的类,接口和关键字处于同一行
2）左大括号一律与它所从属的方法和构造函数处于同一行
3）左大括号一律与它所从属的枚举声明和枚举常量处于同一行
4）左大括号一律与它所从属的注释类型声明处于同一行
5）数组初始化中左大括号一律与声明处于同一行:
6）所有区域都要使用大括号，例如if语句中只有一条语句也要用大括号括起来。
换行（NewLines）
1）局域变量（localvariables）和成员不与其注释在同一行，不许使用与代码同行的注释，注释往往放在其注释内容上。
2）一行最长为120个字符。
3）同一行不能有多个声明，声明放置到新行中
长度（Length）
1）文件长度不超过1000行，建议。
2）方法长度不超过200行，建议。
4.声明
声明的基本原则是遵守Java语言规范，并遵从习惯用法。
类、接口
声明定义：
[可见性][（'abstract'|'final'）][Class|Interface]class_name
[（'extends'|'implements'）][父类或接口名]
如：
publicclassLoginActionextendsBaseActionimplemnetsActionListener方法
良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：
尽量限制成员函数的可见性。
如果成员函数没必要公有
（public），就定义为保护（protected）；没必要保护。
方法
声明定义：
[可见性][（'abstract'|'final'）]['synchronized'][返回值类型]method_name（参数
列表）[（'throws'）][异常列表]
如：
publicListlistAllUsers（）throwsDAOException
若有toString（）,equals（）,hashCode（）,colone（）等重载自Object的方法，应将其放在类的最后。
声明顺序：
构造方法，静态公共方法，公共方法，静态私有方法，受保护方法，私有方法，继承自Object的方法
字段
字段定义语法规范：
[（‘public’|’private’|’protected’）]
[（‘final’|’volatile’）][‘static’][‘transient’]
data_typefield_name[‘=’expression]‘;’
若没有足够理由，不要把实例或类变量声明为公有。
公共和保护的可见性应当尽量避免，所有的字段都建议置为私有，由获取和设置成员函数（Getter、Setter）访问。
不允许“隐藏”字段，即给局部变量所取的名字，不可与另一个更大范围内定义的字段的名字相同（或相似）。
例如，如果把一个字段叫做firstName，就不要再生成一个局部变量叫做firstName，或者任何易混肴的名字，如fistName。
数组声明时当将"[]"跟在类型后，而不是字段名后，如：
Integer[]ai=newInteger[2];//一个整数对象数组，用于...
Integeraj[]=newInteger[3];//不要用这种数组声明方式
一行代码只声明一个变量，仅将一个变量用于一件事。
声明顺序：
常量，类成员变量，实例变量，公有字段，受保护字段，私有字段。
5.其他约束
类成员可见性
说明：
检查类成员的可见性。
只有staticfinal成员是public的，其他的类成员都是private的.
赋值（Assignment）
1不允许内部赋值,如:
Strings=Integer.toString（i=2）;
2不允许更改的循环控制变量
比如，一个for循环的循环数是只应该在最后的i++中更改的，如果出现以下代码：
for（inti=0;i<1;i++）{
i++;//这里是极可能是程序员大意写出来的。
}
3参数赋值
对方法的参数赋值一般说来，是不好的编程技巧。
而强制开发人员声明一个final
参数，也不够友好。
publicvoidtest1（inta）{
a=1;//checkstyle报检查错误
}
函数的参数个数不超过5个，若需要传递多个参数时，当使用一个容纳这些参数的对象进行传递，以提高程序的可读性和可扩展性，还可以考虑使用动态参数。
条件表达式使用
1简化的条件表达式，检查过度复杂的条件表达式，比如：
（b==true）,b||true,!
false,难读且容易出错。
这里最好简化使用。
无效语句
说明：
检查无效语句（单独';'语句） .
publicvoidtest4（）{
if（true）;//if语句后的';'号引起checkstyle检查错误
doConditionalStuff（）;
doUnconditionalStuff（）;
}
Import规范
避免引用未使用的import检查.
以下几种import是没用/没意义的：
没有被用到，重复的，importjava.lang的，import与该类在同一个package的。
另外不要引入“.*”的包，会有性能问题。
String比较
检查进行字符串比较时，不能用==或者!
=，应该用equals。
另外需要先检查一个可能为null的字符串是否在equals（）比较的左边，避免空指针异常。
注释要求
1）项目需要导入统一的注释模板。
需要添加javadoc注释的地方包括：
所有的非私有变量，所有的public，protected非私有方法，类和接口。
Ø注释应该增加代码的清晰度。
代码注释的目的是要使代码更易于被其他开发人员理解。
Ø如果你的程序不值得注释，那么它很可能也不值得运行。
Ø避免使用装饰性内容。
Ø保持注释的简洁。
Ø注释信息不仅要包括代码的功能，还应给出原因。
Ø不要为注释而注释。
Ø除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。
2）编写Java类/接口时，在类/接口、非私有方法、非私有变量的上一行用/**前导并回车可自动产生JavaDoc注释的格式，将%x%修改为实际的内容。
3）在非私有方法的JavaDoc注释的补充说明
一般有参数有返回值有异常的方法自动生成的注释类似如下（不包括红色字体的内容）：
/**
*
*%方法的一句话概述（注：
句号不能删除，本注应删除）%。
*
%方法详述（简单方法可不必详述）%
*@params说明参数含义
*@return说明返回值含义
*@throwsIOException说明发生此异常的条件
*@throwsNullPointerException说明发生此异常的条件
*/
默认生成的JavaDoc注释没有这些红色字体的内容，它们必须被填入实际内容，才能产生优美格式的JavaDoc文档。
4）以下情况必须添加注释：
Ø私有方法，除构造函数外，可以添加该方法的注释（JavaDoc注释或非JavaDoc注释均可）。
Ø复杂方法（如方法体超过30行），或包含关键算法的方法，必须对内部的操作步骤添加注释（行注释//或块注释/**/均可）。
Ø方法内部多次转换含义的变量，必须对该变量的含义发生变化时添加注释。
Ø方法内部存在不易理解的多个分支条件的表达式，必须对每个分支添加注释。
以下情况可不必添加注释：
ØPO类的属性（私有变量），由于已经在get/set方法内添加JavaDoc注释，因此可不必添加。
Tryif嵌套层次和分支复杂度
try嵌套层数，最多2层，也就是两个try。
If的嵌套层数，最多4层。
确保函数的分支复杂度没有超出限制。
该复杂度是通过考察大部分函数（构造函数，一般方法，静态初始函数，实例初始化函数）中的if,while,do,for,?
:
catch,switch,case语句和&&,||的操作符的数目来计算得到的。
它表示了通过一个函数的最少分支数，也因此体现了需要进行的测试数目。
一般而言1-4是优秀，5-7是合格。
8-10看情况重构。
11个以上一定要马上重构。
Switch语句
确保switch语句的default一定在最后出现。
虽然java语法允许default可以放在switch中的任何位置，但是把它放在各个case的最下面是可读性最强的，如果不写default,就会产生逻辑错误，却没有提示。
6.设计规范
类与接口
1.
1）基本原则
类的划分粒度，不可太大，造成过于庞大的单个类，也不可太细，从而使类的继承太深。
一般而言，一个类只做一件事；另一个原则是根据每个类的职责进行划分，比如用User来存放用户信息，而用UserDAO来对用户信息进行数据访问操作（比如存取数据库），用UserService来封装用户信息的业务操作等等。
多个类中使用相同方法时将其方法提到一个接口中或使用抽象类，尽量提高重用度。
将不希望再被继承的类声明成
final，例如某些实用类，但不要滥用final，否则会对系统的可扩展性造成影响。
将不希望被实例化的类的缺省构造方法声明成private。
2）抽象类与接口
一般而言：
接口定义行为，而抽象类定义属性和公有行为，注意两者间的取舍，在设计中，可由接口定义公用的行为，由一个抽象类来实现其部分或全部方法，以给子类提供统一的行为定义，可参考Java集合等实现。
多使用接口，尽量做到面向接口的设计，以提高系统的可扩展性。
3）继承与组合
尽量使用组合来代替继承，一则可以使类的层次不至于过深，而且会使类与类，包与包之间的耦合度更小，更具可扩展性。
尽量避免在深度继承的类的构造函数中建立对象。
方法
2.
1）基本原则
一个方法只完成一项功能，在定义系统的公用接口方法外的方法应尽可能的缩小其可见性。
避免用一个类实例去访问其静态变量和方法。
避免在一个较长的方法里提供多个出口：
//不要使用这钟方式，当处理程序段很长时将很难找到出口点
if（condition）{
returnA;
}else{
returnB;
}
//建议使用如下方式
Stringresult=null;
if（condition）{
result=A;
}else{
result=B;
}
returnresult;
表达式与语句
3.
表达式和语句当清晰、简洁，易于阅读和理解，避免使用晦涩难懂的语句。
每行至多包含一条执行语句，过长当换行。
避免在构造方法中执行大量耗时的初始化工作，应当将这中工作延迟到被使用时再创建相应资源，如果不可避免，则当使用对象池和Cache等技术提高系统性能。
尽量在声明局部变量的同时初始化。
唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。
一般而言，在含有多种运算符的表达式中使用圆括号来避免运算符优先级问题，是个好方法。
即使运算符的优先级对你而言可能很清楚，但对其他人未必如此。
你不能假设别的程序员和你一样清楚运算符的优先级。
不要为了表现编程技巧而过分使用技巧，简单就好。
控制语句
判断中如有常量，则应将常量置于判断式的右侧。
如：
if（true==isAdmin（））...
尽量不使用三目条件的嵌套。
所有if语句必须用{}包括起来,即便是只有一句：
if（true）{
//dosomething......
}
if（true）
i=0;//不要使用这种
当有多个else分句时当分别注明其条件，注意缩进并对齐，如：
//先判断i是否等于1
if（i==1）{//if_1
//.....
}//然后判断i==2
elseif（i==2）{
//i==2说明。
。
。
。
。
。
j=i;
}//如果都不是（i>2||i<1）
else{
//说明出错了
//....
}//endif_1
过多的else分句请将其转成switch语句或使用子函数。
每当一个case顺着往下执行时（因为没有break语句），通常应在break语句的位置添加注释。
如：
switch（condition）{
caseABC:
//statements;
//继续下一个CASE
caseDEF:
//statements;
break;
caseXYZ:
//statements;
break;
de
升级会员 