云护宝技术开发部Java软件开发规范.docx

1、云护宝技术开发部Java软件开发规范云护宝有限公司技术开发部软件开发规范版本v1.0.0版本控制版本号状态类型修改人审核人曰期描述V1.0.0完结初稿蒋润青2018-05-21目录1、前言 41.1编写目的 41.2范围 42、Java程序代码规范 52.1命名规范 52.2代码规范 73、代码注释规范 103.1文件版权信息 103.2类和接口的注释 103.3方法的注释 103.4初版代码中注释 113.5新增代码中注释 113.6修改代码中注释 113.7 XML文件中注释 124、SVN使用规范 125、 RESTful api接口 131、前言1.1编写目的为规范项目组的应用开发、解

2、决开发中的代码规范问题和命名规范问题、促进开发工作顺利有序地进行，特制定本开发规范手册。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文件名称必

3、须以大写字母开头，可以使用2-4个英文单词（尽量不要用缩写）组成每个单词的首 字母大写。文件名称必须能说明文件内代码功能。对java文件大致分为接口，实现类，模型，静态类型声明，逻辑类，工具类。a） 接口类命名：IXxxxService。b） 实现类命名：Xxxxxlmpl。实现类的名称前段必须与接口一致说明是哪个接口的实现。c） 模型类命名：XxxxxModel或XxxxxManager。模型类的名称必须与数据库表对应。d） 静态类型声明：XxxxxType。e） 逻辑类：Mapper逻辑类为执行sql并返回结果的Model加工工厂。逻辑类返回Xxxx或 由 Xxxx 组成的 ArrayLi

4、st，List。等对象。f） 工具类：如 StringUtil， DateUtil 等。2.1.3方法名命名规范基本规范如下：a）方法名应该能够简单描述出该方法实现的功能，如deleteUsers；b） 方法名尽量不使用缩写，除非它是众所周知的，如可以使用db表示database;c） 方法名可以有两个或三个单词组成，但尽量不要多于三个以上；d） 方法名中由多个单词合成，第一个单词通常为动词，首字母小写，中间的每个单词的首字母都要大写，如删除用户：deleteUsers；e） 方法名中不要使用下划线字符。2.1.4常量名命名规范常量名也应当有一定的意义，常量名均为大写。如果是由多个单词构成，可

5、以用下划线隔开，如果是 对象类型的常量，则是大小写混合，由大写字母把单词隔开。如：private const int PI=3. 1415926； int YEAR,String TITLE = “XXXX”； int WEEK_OF_MONTH；2.1.5变量名命名规范在程序中变量的名称要求能够体现出就是的功能，如果是单个单词那么变量名用小写，例如：email 如果变量名是多个单词组成那么首字母小写，中间的每个单词的首字母都要大写。例如： isSuperUser;userLogin。如果是循环变量，那么变量名必须是一个小写字母，如：i，j，k。变量名也尽量不使用缩写，且一定要有含义，不能使用

6、没有表达意义的变量名，如：a1;a2;mmm。2.2代码规范2.2.1类引用规范import时使用星号“*”会消耗更多的应用资源，因此要避免使用，在当前类如果引用其它类的方法， 那么就明确的import该方法所属的类文件。此外要避免import的类没有被使用或者重复。2.2.2避免使用内部赋值语句不允许这种书写方式：String s = Integer.toString(i = 2);2.2.3避免魔法数也叫MagicNumber,会让程序不可读。说明：所谓魔法数值，是指在代码中直接出现的数值，而只有在这个数值记述的那部分代码中才能明确了解其含义。魔法数值使代码的可读性大大下降。而且，如果同样

7、的数值多次出现时，到底这些数值是不是带有同 样的含义呢，谁也说不清楚。另一方面，如果本来应该使用相同数值的地方，一旦用错了，也很难发现。 因此，需要注意以下几点，极力避免使用魔法数值。比如：isDelete=0 表示的什么意思？所以，这里的0就是一个魔法数。建议改用下面的书写方式：public static final int DELETE= 0 ; /删除状态 isDelete = DELETE;这样我们就知道，原来是把isDelete变量的值初始化为“DELETE”,删除。2.2.4字符串(String)的比较检查字符串的比较时没有使用=或!=。正确的写法应该是使用equals，Strin

8、gUtils方法，字符串在前，变量在后，避免空指针异常。如：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语句字符串进行拆分，并且每行字符串前端需要有一空格。普通代码也要相似处理，尽量不需要拖动滚动条而显示完整代码，

9、例子如下： /实现XXXXXXXXX功能的SQL语句3、代码注释规范以下注释是以java程序为例，C+的代码注释符号和java略有不同，但需要表达的内容完全一样3.1文件版权信息3.2类和接口的注释3.3方法的注释/* * return com.yhb.core.util.apiResult.ResponseResult * author JiangRunqing * Description 删除公告牌 * Date 2018/5/18 18:20 * Param id */3.4初版代码中注释初版代码中使用的注释方法如下：/数据库驱动String CLASSFORNAME=com.mysql

10、.jdbc.Driver;添加注释时要有几点注意：a） 确保所有的代码注释都是单独的一行，而不是与代码同行；b） 注释全部采用中文，要能明确表达出被注释的代码所实现的功能；c） 注释不宜过长和换行，通俗易懂的代码无需注释，在变量声明、条件处理（if.else）、循环语 句、标识位使用（如整型变量flag，0、1、2等分别表示什么）的时候必须添加注释。3.5新增代码中注释当在己经发布版本的代码中増加新的代码，则以如下方式添加注释: /20110625张三新增功能：声明数据库驱动BEGIN String CLASSFORNAME=com.mysql.jdbc.Driver; /20110625张三

11、新增 END3.6修改代码中注释当在己经发布版本的代码中修改代码，需要把原代码注释掉之后，再添加说明，如下: /20110625张三修改修改原因：重新声明数据库驱动BEGIN/String CLASSFORNAME=com.mysql.jdbc.Driver;String CLASSFORNAME=oracle. jdbc. driver. OracleDriver;/20110625 张三 修改 END3.7 XML文件中注释4、SVN使用规范使用SVN使用遵守以下的原则a） 开发人员每天签到后必须从SVN服务器上获得当前最新版本。b） 每日结束工作后必须将代码提交至SVN服务器并保证代码可

12、编译。c） 开发人员对代码进行修改时必须将被修改文件checkout后进行修改。d） 设计文档，程序编码都必须放到版本控制中去。e） 有重大修改，或影响其他人工作的修改，要发送QQ群里消息或邮件通知。f） 版本服务器的数据要定期进行备份。g） 修改完成的文档，编码要迅速提交到版本控制服务器。h） 在本地测试通过的文档和程序才能提交到版本控制服务器，如果因特殊需要要求提交到版本服务器，但本机测试还没通过时，请注明。i） 项目形成一个可测试的版本之后，要求测试人员在未完成当前版本的测试之前，不允许更新下一 版的代码，从而造成不必要的测试版本错乱。5、RESTful api接口常用的HTTP动词有下面四个（括号里是对应的SQL命令）。GET（SELECT）：从服务器取出资源（一项或多项）。POST（CREATE）：在服务器新建一个资源。PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。DELETE（DELETE）：从服务器删除资源。例如：GET /department：列出所有商品POST /department：新建一个商品GET /department/ID：获取某个指定商品的信息PUT /department：更新某个指定商品的信息DELETE /department/ID：删除某个商品