云护宝技术开发部Java软件开发规范.docx
《云护宝技术开发部Java软件开发规范.docx》由会员分享,可在线阅读,更多相关《云护宝技术开发部Java软件开发规范.docx(7页珍藏版)》请在冰豆网上搜索。
云护宝技术开发部Java软件开发规范
云护宝有限公司技术开发部
软件开发规范
版本v1.0.0
版本控制
版本号
状态
类型
修改人
审核人
曰期
描述
V1.0.0
完结
初稿
蒋润青
2018-05-21
目录
1、前言4
1.1编写目的4
1.2范围4
2、Java程序代码规范5
2.1命名规范5
2.2代码规范7
3、代码注释规范10
3.1文件版权信息10
3.2类和接口的注释10
3.3方法的注释10
3.4初版代码中注释11
3.5新增代码中注释11
3.6修改代码中注释11
3.7XML文件中注释12
4、SVN使用规范12
5、RESTfulapi接口13
1、前言
1.1编写目的
为规范项目组的应用开发、解决开发中的代码规范问题和命名规范问题、促进开发工作顺利有序地进行,特制定本开发规范手册。
1.2范围
适用于项目开发组所有人员。
2、Java程序代码规范
2.1命名规范
2.1.1包名命名规范
包名必须均为小写。
包名需要使用英文说明包内代码功能,不能采用拼音。
具体示例如下:
以com.yhb.apimanager.为例:
第一段com代表公司,org代表组织。
第二段yhb为公司名称云护宝。
第三段api为云护宝api项目名称。
对于与各项目之间的通用包如util包、db包直接隶属于com.yhb.core包下。
通用包的内的代码必须不依赖于任何项目,可独立编译。
2.1.2文件名命名规范
Java文件名称必须以大写字母开头,可以使用2-4个英文单词(尽量不要用缩写)组成每个单词的首字母大写。
文件名称必须能说明文件内代码功能。
对java文件大致分为接口,实现类,模型,静态类型声明,逻辑类,工具类。
a)接口类命名:
IXxxxService。
b)实现类命名:
Xxxxxlmpl。
实现类的名称前段必须与接口一致说明是哪个接口的实现。
c)模型类命名:
XxxxxModel或XxxxxManager。
模型类的名称必须与数据库表对应。
d)静态类型声明:
XxxxxType。
e)逻辑类:
Mapper逻辑类为执行sql并返回结果的Model加工工厂。
逻辑类返回Xxxx或由Xxxx组成的ArrayList,List。
等对象。
f)工具类:
如StringUtil,DateUtil等。
2.1.3方法名命名规范
基本规范如下:
a)方法名应该能够简单描述出该方法实现的功能,如deleteUsers;
b)方法名尽量不使用缩写,除非它是众所周知的,如可以使用db表示database;
c)方法名可以有两个或三个单词组成,但尽量不要多于三个以上;
d)方法名中由多个单词合成,第一个单词通常为动词,首字母小写,中间的每个单词的首字母都要
大写,如删除用户:
deleteUsers;
e)方法名中不要使用下划线字符。
2.1.4常量名命名规范
常量名也应当有一定的意义,常量名均为大写。
如果是由多个单词构成,可以用下划线隔开,如果是对象类型的常量,则是大小写混合,由大写字母把单词隔开。
如:
privateconstintPI=3.1415926;intYEAR,
StringTITLE=“XXXX”;intWEEK_OF_MONTH;
2.1.5变量名命名规范
在程序中变量的名称要求能够体现出就是的功能,如果是单个单词那么变量名用小写,例如:
email如果变量名是多个单词组成那么首字母小写,中间的每个单词的首字母都要大写。
例如:
isSuperUser;userLogin。
如果是循环变量,那么变量名必须是一个小写字母,如:
i,j,k。
变量名也尽量不使用缩写,且一定要有含义,不能使用没有表达意义的变量名,如:
a1;a2;mmm。
2.2代码规范
2.2.1类引用规范
import时使用星号“*”会消耗更多的应用资源,因此要避免使用,在当前类如果引用其它类的方法,那么就明确的import该方法所属的类文件。
此外要避免import的类没有被使用或者重复。
2.2.2避免使用内部赋值语句
不允许这种书写方式:
Strings=Integer.toString(i=2);
2.2.3避免魔法数
也叫MagicNumber,会让程序不可读。
说明:
所谓魔法数值,是指在代码中直接出现的数值,而只有在这个数值记述的那部分代码中才能明确了解其含义。
魔法数值使代码的可读性大大下降。
而且,如果同样的数值多次出现时,到底这些数值是不是带有同样的含义呢,谁也说不清楚。
另一方面,如果本来应该使用相同数值的地方,一旦用错了,也很难发现。
因此,需要注意以下几点,极力避免使用魔法数值。
比如:
isDelete=0
表示的什么意思?
所以,这里的"0"就是一个魔法数。
建议改用下面的书写方式:
publicstaticfinalintDELETE=0;//删除状态
isDelete=DELETE;
这样我们就知道,原来是把isDelete变量的值初始化为“DELETE”,删除。
2.2.4字符串(String)的比较
检查字符串的比较时没有使用==或!
=。
正确的写法应该是使用equals,StringUtils方法,字符串在前,变量在后,避免空指针异常。
如:
if("something".equals(x))
2.2.5嵌套的try层次控制
避免try-catch的嵌套的层次过多而降低代码可读性。
建议最大的嵌套深度不超过3层。
2.2.6控制return语句的数量
如果return语句太多,说明某个方法需要实现的功能太多,而且很难阅读,这个时候就需要重构。
建议每个方法最多有5个return语句。
2.2.7规范SQL语句的编写
如果需要编写SQL语句,则当编写的SQL语句过长时,需要对SQL语句字符串进行拆分,并且每行字符串前端需要有一空格。
普通代码也要相似处理,尽量不需要拖动滚动条而显示完整代码,
例子如下:
//实现XXXXXXXXX功能的SQL语句
3、代码注释规范
以下注释是以java程序为例,C++的代码注释符号和java略有不同,但需要表达的内容完全一样
3.1文件版权信息
3.2类和接口的注释
3.3方法的注释
/**
*@returncom.yhb.core.util.apiResult.ResponseResult
*@authorJiangRunqing
*@Description删除公告牌
*@Date2018/5/1818:
20
*@Param[id]
**/
3.4初版代码中注释
初版代码中使用的注释方法如下:
//数据库驱动
StringCLASSFORNAME="com.mysql.jdbc.Driver";
添加注释时要有几点注意:
a)确保所有的代码注释都是单独的一行,而不是与代码同行;
b)注释全部采用中文,要能明确表达出被注释的代码所实现的功能;
c)注释不宜过长和换行,通俗易懂的代码无需注释,在变量声明、条件处理(if...else)、循环语句、标识位使用(如整型变量flag,0、1、2等分别表示什么)的时候必须添加注释。
3.5新增代码中注释
当在己经发布版本的代码中増加新的代码,则以如下方式添加注释:
//20110625张三新增功能:
声明数据库驱动BEGIN
StringCLASSFORNAME="com.mysql.jdbc.Driver";
//20110625张三新增END
3.6修改代码中注释
当在己经发布版本的代码中修改代码,需要把原代码注释掉之后,再添加说明,如下:
//20110625张三修改修改原因:
重新声明数据库驱动BEGIN
//StringCLASSFORNAME="com.mysql.jdbc.Driver";
StringCLASSFORNAME="oracle.jdbc.driver.OracleDriver";
//20110625张三修改END
3.7XML文件中注释
4、SVN使用规范
使用SVN使用遵守以下的原则
a)开发人员每天签到后必须从SVN服务器上获得当前最新版本。
b)每日结束工作后必须将代码提交至SVN服务器并保证代码可编译。
c)开发人员对代码进行修改时必须将被修改文件checkout后进行修改。
d)设计文档,程序编码都必须放到版本控制中去。
e)有重大修改,或影响其他人工作的修改,要发送QQ群里消息或邮件通知。
f)版本服务器的数据要定期进行备份。
g)修改完成的文档,编码要迅速提交到版本控制服务器。
h)在本地测试通过的文档和程序才能提交到版本控制服务器,如果因特殊需要要求提交到版本服务器,但本机测试还没通过时,请注明。
i)项目形成一个可测试的版本之后,要求测试人员在未完成当前版本的测试之前,不允许更新下一版的代码,从而造成不必要的测试版本错乱。
5、RESTfulapi接口
常用的HTTP动词有下面四个(括号里是对应的SQL命令)。
GET(SELECT):
从服务器取出资源(一项或多项)。
POST(CREATE):
在服务器新建一个资源。
PUT(UPDATE):
在服务器更新资源(客户端提供改变后的完整资源)。
DELETE(DELETE):
从服务器删除资源。
例如:
GET/department:
列出所有商品
POST/department:
新建一个商品
GET/department/ID:
获取某个指定商品的信息
PUT/department:
更新某个指定商品的信息
DELETE/department/ID:
删除某个商品