软件工程建设标准文档格式.docx
- 文档编号:17465570
- 上传时间:2022-12-01
- 格式:DOCX
- 页数:15
- 大小:27.43KB
软件工程建设标准文档格式.docx
《软件工程建设标准文档格式.docx》由会员分享,可在线阅读,更多相关《软件工程建设标准文档格式.docx(15页珍藏版)》请在冰豆网上搜索。
使用完整单词,避免缩写词(除非该缩写词被更广泛使用,像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、控制器
层控件器命名规范
以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作为值对象收集页面数据
2.代码排版规范
排版主要为了界面规范,一方面为了代码清晰,另外可以方便进行代码合并时减少因排版引起不一致。
在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行,建议。
3.声明
声明的基本原则是遵守Java语言规范,并遵从习惯用法。
类、接口
声明定义:
[可见性][('
abstract'
|'
final'
)][Class|Interface]class_name
[('
extends'
implements'
)][父类或接口名]
publicclassLoginActionextendsBaseActionimplemnetsActionListener方法
良好的程序设计应该尽可能减小类与类之间耦合,所遵循的经验法则是:
尽量限制成员函数的可见性。
如果成员函数没必要公有(public),就定义为保护(protected);
没必要保护。
方法
)]['
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];
//不要用这种数组声明方式
一行代码只声明一个变量,仅将一个变量用于一件事。
常量,类成员变量,实例变量,公有字段,受保护字段,私有字段。
4.其他约束
类成员可见性
说明:
检查类成员的可见性。
只有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注释的补充说明
一般有参数有返回值有异常的方法自动生成的注释类似如下(不包括红色字体的内容):
/**
*
*%方法的一句话概述(注:
句号不能删除,本注应删除)%。
*<
p>
%方法详述(简单方法可不必详述)%<
/p>
*@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,就会产生逻辑错误,却没有提示。
5.设计规范
类与接口
1)基本原则
类的划分粒度,不可太大,造成过于庞大的单个类,也不可太细,从而使类的继承太深。
一般而言,一个类只做一件事;
另一个原则是根据每个类的职责进行划分,比如用User来存放用户信息,而用UserDAO来对用户信息进行数据访问操作(比如存取数据库),用UserService来封装用户信息的业务操作等等。
多个类中使用相同方法时将其方法提到一个接口中或使用抽象类,尽量提高重用度。
将不希望再被继承的类声明成final,例如某些实用类,但不要滥用final,否则会对系统的可扩展性造成影响。
将不希望被实例化的类的缺省构造方法声明成private。
2)抽象类与接口
一般而言:
接口定义行为,而抽象类定义属性和公有行为,注意两者间的取舍,在设计中,可由接口定义公用的行为,由一个抽象类来实现其部分或全部方法,以给子类提供统一的行为定义,可参考Java集合等实现。
多使用接口,尽量做到面向接口的设计,以提高系统的可扩展性。
3)继承与组合
尽量使用组合来代替继承,一则可以使类的层次不至于过深,而且会使类与类,包与包之间的耦合度更小,更具可扩展性。
尽量避免在深度继承的类的构造函数中建立对象。
数据交换
数据交换标准的主题是数据文件的格式,信息表达的标准化、代码化是信息交换的基础,二者之间的关系类似于单词与句子之间的关系,信息表达标准是数据交换标准的组成部分和基本内容。
<
?
xmlversion"
1.0"
encoding="
GB2312"
>
xs:
schematargetNamespace=〃Report00031009"
xmlns:
xs="
http:
//www.w3.org/2001/XMLSchema"
elementFormDefault="
unqualified"
attributeFormDefault=〃unqualified〃>
elementname=〃Report00031009"
complexType>
1)获取文件服务参数
数据交换服务获取文件时的输入参数和返回值如下
参数名称
参数类型
参数描述
requestStr
String
输入参数,按“接入服务输入参数规范”编写参数
fileObject
DataHandler数组
返回值
功能说明
数据交换对外提供接口服务
一个方法只完成一项功能,在定义系统的公用接口方法外的方法应尽可能的缩小其可见性。
避免用一个类实例去访问其静态变量和方法。
避免在一个较长的方法里提供多个出口:
//不要使用这钟方式,当处理程序段很长时将很难找到出口点
if(condition){
returnA;
}else{
returnB;
//建议使用如下方式
Stringresult=null;
result=A;
result=B;
returnresult;
表达式与语句
表达式和语句当清晰、简洁,易于阅读和理解,避免使用晦涩难懂的语句。
每行至多包含一条执行语句,过长当换行。
避免在构造方法中执行大量耗时的初始化工作,应当将这中工作延迟到被使用时再创建相应资源,如果不可避免,则当使用对象池和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:
break;
caseXYZ:
defaul
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 软件工程 建设 标准
![提示](https://static.bdocx.com/images/bang_tan.gif)