Java代码标准说明.doc

Java代码标准说明 1. 环境配置21.1. 软件21.2. 项目导入21.3. 项目编码配置32. 项目通用命名规则62.1. 命名方式62.2. 方法命名规则62.3. 变量命名规则62.4. 常量命名规则72.5. 注释72.6. 注释范围82.7. Controller、Service、Dao 等中的方法命名92.8. JSP页面命名103. 代码书写规范103.1. 返回值103.2. 异常113.3. 换行(Wrapping Lines)133.4. 声明(Declaration)143.5. 初始化(Initialization)153.6. 布局(Placement)153.7. 简单语句(Single Statement)163.8. 复合语句(Compound Statements)163.9. 返回语句(return Statements)163.10. for语句(for Statements)173.11. while语句switch(while Statements)173.12. 空行(Blank Lines)183.13. 空格(Blank Spaces)183.14. 圆括号(Parentheses)193.15. 变量赋值(Variable Assignments)203.16. 去除警告204. 代码质量214.1. 统一编码规范、代码样式214.2. 静态代码分析214.3. 单元测试214.4. 持续集成224.5. 代码评审和重构221. 环境配置1.1. 软件软件名称版本备注Myeclipse6.5试用版JDKJdk.1.6.0_45sunJDK开源Tomcat6.0.37Apache开源Mysql5.0.18/5.1开源SQLyog9.6.2试用版SVNsubeclipse-site-1.6.5插件SVN客户端TortoiseSVN 1.6.7插件1.2. 项目导入1、选择SVN地址 输入帐号密码完成即可1.3. 项目编码配置文项目所有编码格式统一采用UTF-8 设置修改types 和methods注释的方法修改以上则类名自动加注释，需要修改里边的信息 方法名注释：在方法的前面输入” /* ” b然后回车自动出现注释调整样式即可。 2. 项目通用命名规则2.1. 命名方式文件名、变量名称使用有意义的英文（或缩写）进行命名，名称与数据表结构的名称命名保持一致，便于提高查阅效率。所有由多个单词组成的名称统一用驼峰法则进行命名。驼峰法则是由一个或多个单字连结在一起，而构成的唯一识别字时，第一个单字以小写字母开始，第二个单字的首字母大写或每一个单字的首字母都采用大写字母，例如： 业务名称为角色，则命名为 RoleController 、RoleServiceImpl 、findUniqueEntity 等。所有的命名根据业务名称的英文或者中文拼音，优先采用英文。2.2. 方法命名规则方法名应是一个动词或动名结构，采用大小写混和的方式，其中第一个单词的首字母用小写，其后单词的首字母大写。例如：Xxxxx.getBmList()；每个方法前必须加说明包括：参数说明、返回值说明、异常说明。如果方法名实在是太长可以对变量名缩写，但是必须添加相应的说明。2.3. 变量命名规则变量命名一般采用大小写混和的方式，第一个单词的首字母小写，其后单词的首字母大写，变量名一般不要用下划线或美元符号开头。变量名应简短且有意义，即，能够指出其用途。除非是一次性的临时变量，应尽量避免单个字符的变量名。（1）类的实例对象定义如下：Person person;（2）同一个类的多个对象可以采用一下定义方式：Person person1；Person person2；（3）集合类的实例命名使用集合包含元素的英文名称的复数表示，例如：Vector persons;（4）如果变量名实在是太长可以对变量名缩写，但是必须在类说明或方法说明部分（视缩写的范围而定）进行说明。（5）数组的声明要用int packets的形式，而不要用int packets。2.4. 常量命名规则类常量和ANSI常量的命名应全部用大写，单词间用下划线隔开。例如：final static int MIN_WIDTH = 4；2.5. 注释Java程序有两类注释：实现注释(implementation comments)和文档注释(document comments)。实现注释是那些在C+中见过的，使用/*/和/界定的注释。文档注释(被称为“doc comments”)是Java独有的，并由/*/界定。文档注释可以通过javadoc工具转换成HTML文件。实现注释用以注释代码或或者实现细节。文档注释从实现自由(implemtentation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息。例如，相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。在注释里，对设计决策中重要的或者不是显而易见的地方进行说明是可以的，但应避免提供代码中已清晰表达出来的重复信息，多余的注释很容易过时。通常应避免那些代码更新就可能过时的注释。类以及类中的每个方法必须有注释。方法中的代码关键部分必须有注释，解释代码的意思。 文本注释 类注释 /* * function: 增删改查组件规范接口 * project Xcj * package com.xcj.admin.base * fileName BaseDao.java * createDate 2010-03-30 下午05:28:03 * author xx_xx * email */ 类中方法注释 /* * function: 增加一个entity对象，返回是否添加成功 * createDate 2010-03-30 下午05:28:38 * author su_jian * param 对象类型 * param entity 对象 * return boolean true/false * throws DataAccessException */ 单行注释/获取系统管理员的所有权限2.6. 注释范围 a) 类的方法名和类名必须有注释。例如 /* * function: 增加一个entity对象，返回是否添加成功 * createDate 2014-03-30 下午05:28:38 * author su_jian * param 对象类型 * param entity 对象 * return boolean true/false * throws DataAccessException */ b) 类调用的方法以及关键代码注释。例如/进行静态化处理staticService.buidSingleArticle(article.getId();/生成二维码图片staticService.buidQRcode(article.getId(); c) 配置文件（Spring、DB、等）代码注释。例如 $c3p0.initialPoolSize $c3p0.minPoolSize2.7. Controller、Service、Dao 等中的方法命名方法类型命名规则举例（参数自己定义）初始化init+操作对象init ()新增save+操作对象save()、saveObject()删除del+操作对象sdel()、delObject ()修改update+操作对象update()、updateObject ()新增+修改edit+操作对象edit()、editObject ()查看view+操作对象view()、viewObject ()获取单个对象get+操作对象get()、getObject ()获取列表数据getListBypage+操作对象sgetXxListByPage()获取集合数据getXList+操作对象sgetXxList()、getXxList Object()获取树形数据getXTree+操作对象sgetXxTree()、getXxTreeObject ()前后插入save(Before/After)+操作对象 saveObject ()/saveBeforeObject ()禁用disabled+操作对象disabled()、disabledObject()启用或激活active+操作对象sactive()、activeObject()授权assign+操作对象sassign()、assignObject ()撤销unassign+操作对象sunassign()、unassignObject ().2.8. JSP页面命名页面类型命名规则举例（参数自己定义）主页操作对象index.jspobjectindex.jsp新增页面操作对象save .jspobjectsave.jsp修改页面操作对象edit.jspobjectedit.jsp查看页面操作对象detail.jspobjectdetail.jsp授权操作对象assign.jspobjectassign.jsp. 3. 代码书写规范类的方法的代码行数不能过长，尽量控制在100行（90%），长的方法要拆分成私有函数。3.1. 返回值返回值的情况，如果只需要一个对象里边的属性值，则无需返回整个对象。返回值就行。 在一般情况下，方法返回值不应返回null。而是尽量使用异常代替返回null。如果在特殊情况必须返回null, 必须在方法说明中加以特别说明，如使用“特别注意”等字样。例如：从一个集合类实例中提取一个对象，因为有些集合类实例是允许null作为键或值的，这个时候用异常取代返回null就不合适了。如果方法的返回值是集合类对象，而且返回的集合对象不包含任何元素时，则应返回0长度或0大小的集合对象。不能返回null。3.2. 异常整个应用系统使用自行设计的唯一异常类，该类包括message（表示错误信息）和ID号（整型，表示异常类型）两部分，该类在创建时是自动获得类名、方法名、行号等信息。在系统开发和上线之后的一段时间内，异常信息要直接发送到浏览器页面，以便于开发人员迅速定位错误。 所有的Controller必须捕获异常，所有的Service、Dao必须把异常抛到上一层进行相应的处理。如果没有相应的Controller则在方法的最前面进行异常的捕获处理。一个try-catch语句应该具有如下格式： try statements; catch (ExceptionClass e) statements; 一个try-catch语句后面也可能跟着一个finally语句，不论try代码块是否顺利执行完，它都会被执行。 try statements; catch (ExceptionClass e) statements; finally statements; 异常DEMO如下： RequestMapping(value = /save, method = RequestMethod.POST)public String save(ValidatedArticle article, Model model) try article.setCreateDate(DateUtil.getCurrentTimeByDate();article.setModifyDate(DateUtil.getCurrentTimeByDate();article.setBoring(1);article.setLoves(1);Integer id = articleService.saveAndGetIdByInteger(article);/以下是获取方法String checkboxs=article.getCheckbox();if(checkboxs!=null)String strs=checkboxs.split(,);for (int i = 0; i strs.length; i+) ArticleTag articleTag= new ArticleTag();articleTag.setArticleId(id);articleTag.setTagId(Integer.valueOf(strsi);articleTagService.save(articleTag); /进行静态化处理staticService.buidSingleArticle(id);/生成二维码图片staticService.buidQRcode(id); catch (Exception e) log.error(文章:保存对象出错： + e.getMessage();e.printStackTrace();return redirect:/admin/article/articleList_jsp; 其中红色部分为异常处理。即所有的Controller中方法必须进行异常的处理。 常用工具类中异常DEMO如下： public static String readTxtFile(String filePath)InputStreamReader inputReader = null; BufferedReader bufferReader = null; OutputStream outputStream = null; try InputStream inputStream = new FileInputStream(filePath); inputReader = new InputStreamReader(inputStream); bufferReader = new BufferedReader(inputReader); / 读取一行 String line = null; StringBuffer strBuffer = new StringBuffer(); while (line = bufferReader.readLine() != null) strBuffer.append(line); return strBuffer.toString(); catch (IOException e) return null; finally 3.3. 换行(Wrapping Lines)尽量避免一行长度超过80个字符，因为很多终端和工具不能很好处理之。注意：用于文档是的例子应该使用更短的行长，长度一般不超过70个字符。如果超过则使用换行来处理。 / 使用这种方式来换行if (condition1 & condition2)| (condition3 & condition4)| !(condition5 & condition6) doSomethingAboutIt();/ OR USE THISif (condition1 & condition2) | (condition3 & condition4) | !(condition5 & condition6) doSomthingAoutIt();这里有三种可行的方法用于处理三元运算表达式：alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongBooleanExpression) ? beta : gamma;3.4. 声明(Declaration)每行声明变量的数量(Number Per Line)推荐一行一个声明，因为这样以利于写注释。亦即，int level; / indentation levelint size; / size of table要优于，int level, size;不要将不同类型变量的声明放在同一行，例如：int foo, fooarry; / WRONG!注意：上面的例子中，在类型和标识之间放了一个空格，另一种被允许的替代方法是使用制表符：int level; / indentation levelint size; / size of tableObject currentEntry; / currently selected table entry3.5. 初始化(Initialization)尽量在声明局部变量的同时进行初始化。唯一 不这么做理由是变量的初始值依赖于某些先前发生的计算。如果类存在父类，且父类没有被初始化，先初始化父类。 注意：初始化父类时第一被初始化的类永远是object类，父类总在子类之前被初始化。如果类存在一个初始化对象，就执行该方法。 除接口以外，初始化一个类之前必须保证其直接超类已被初始化，并且该初始化过程是由 Jvm 保证线程安全的。另外，并非所有的类都会拥有一个 () 方法，在以下条件中该类不会拥有 () 方法：该类既没有声明任何类变量，也没有静态初始化语句；该类声明了类变量，但没有明确使用类变量初始化语句或静态初始化语句初始化；该类仅包含静态 final 变量的类变量初始化语句，并且类变量初始化语句是编译时常量表达式。 注意：() 方法类变量初始化语句和类型的静态初始化语句与在类中声明的顺序一致 类初始化后，即可调用它的静态方法，或者创建实例。父类静态初始化-子类静态初始化-父类初始化块-父类构造方法-子类初始化块-子类构造方法。3.6. 布局(Placement)只在代码块的开始处声明变量(一个块是指任何被包含在大括号“”和“”中间的代码)。不要在首次用于该变量时才声明之，这会把注意力不集中的程序员搞糊涂，同时会妨碍代码在该作用域内的可移植性。 void myMethod() int int1 = 0; if (condition) int int2 = 0; 该规则的一个例外是for循环的索引变量 for (int i = 0; I maxLoops; i+) 避免声明的局部变量覆盖上一级声明的变量。例如，不要在内部代码块中声明相同的变量名： int count; myMethod() if (condition) int count = 0; / AVOID 3.7. 简单语句(Single Statement) 每行至多包含一条语句，例如： argv+; / Correct argc-; / Correct argv+; argc-; / AVOID!3.8. 复合语句(Compound Statements)复合语句是包含在大括号中的语句序列，形如“ 语句 ”。例如下面各段。 被括其中的语句应该较之复合语句缩进一个层次。 左大括号“”应位于复合语句起始行的行尾；右大括号“”应另起一行并与复合语句首行对齐。 大括号可以被用于所有语句，包括单个语句，只要这些语句是诸如if else或for控制结构的一部分。这样便于添加语句而无需担心由于忘了加括号而引入bug.3.9. 返回语句(return Statements) 个带返回值的return语句不使用小括号“()”，除非它们以某种方式使返回值更显见。例如： return; return myDisk.size(); return (size ? size ; defaultSize);3.10. for语句(for Statements)一个for语句应该具有如下格式： for (initialization; condition; update) statements; 一个空的语句(所有工作都在初始化，条件判断，更新子句中完成)应该具有如下格式： for (initialization; condition; update);当在for语句的初始化或更新子句中使用逗号时，避免因使用三个以上变量，而导致复杂度提高。若需要，可以在for循环之前(为初始化子句)或for循环末尾(为更新子句)使用单独的语句。3.11. while语句switch(while Statements)一个while语句应该具有如下格式： while (condition) statements; 一个空的while语句应该具有如下格式： while (condition);do-while语句(do-while Statements)一个do-while语句应该具有如下格式： do statements; while (condition);switch语句(switch Statements)一个switch语句应该具有如下格式： switch (condition) case ABC: statements; / * falls through */ case DEF: statements; break; case XYZ: statements; break; 3.12. 空行(Blank Lines)空行将逻辑相关的代码段分隔开，以提高可读性。下列情况应总是使用两个空行： 一个源文件的两个片段(section)之间。 类声明和接口声明之间。下列情况应该总是使用一个空行： 两个方法之间。 方法内的局部变量和方法的第一条语句之间。 块注释(参见“5.1.1”)或单行注释(参见5.1.2)之前。 一个方法内的两个逻辑段之间，用以提高可读性。3.13. 空格(Blank Spaces)下列情况应该使用空格： 一个紧跟着括号的关键应该被空格分开，例如： while (true) . 注意：空格不应该置于方法名与其左括号之间，这将有助于区分关键字和方法调用。 空白应该位于参数列表中逗号的后面。 所有的二元运算符，除了“.”，应该使用空格将之与操作数分开。一元操作符和操作数之间不应该加空格，比如：负号(“-”)，自增(“+”)和自减(“-”)。例如： a += c + d; a = (a + b) / (c * d); while (d+ + s+) n+; printSize(“size is ” + foo + “n”); for语句中的表达式应该被空格分开，例如： for (expr1; expr2; expr3)强制转型后应该跟一个空格，例如：myMethod(byte) aNum, (Object) x);myMethod(int) (cp + 5), (int) (i + 3) + 1);3.14. 圆括号(Parentheses) 一般而言，在含有多种运算符的表达式中使用括号来避免运算符优先级问题，是个好方法。即便运算符的优先级对你而言可能很清楚，但对其他人未必如此。你不能假设别的程序员和你一样清楚运算符的优先级。 if (a = b & c =d) / AVOID! if (a = b) & (c = d) / RIGHT 返回值(Returning Values)设法让你的程序结构符合目的。例如： if (booleanException) return true; else return false; 应该代之以如下方法： return booleanException;类似地：if (condition) return x; return y;应该写为： return (condition ? x : y);3.15. 变量赋值(Variable Assignments)避免在一个语句中给多个变量赋相同的值。它很难读懂。例如：fooBar.fChar = barFoo.lchar = c; / AVOID!不要将赋值运算符用在容易与相等关系运算符混淆的地方。例如： if (c+ = d+) / AVOID! (Java disallows) . 应该写成 if (c+ = d+) ! = 0) 不要使用内嵌(embedded)赋值运算符试图提高运行时效率，这是编译器的工作。例如：d = (a = b +c) + r; / AOVID!应该写成 a = b + c; d = a + r;3.16. 去除警告在eclipse 中警告会以感叹号的形式出现， 编码尽量去除警告。一般去除的警告包括一下几类。1、导入未使用的类，请删除。2、未使用的变量，请删除。3、实现序列话的类，没有版本信息，请添加版本信息。4、没有使用泛型的，请加上泛型。4. 代码质量Java项目开发过程中，由于开发人员的经验、Java代码编写习惯，以及缺乏统一的标准和管理流程，往往导致整个项目的代码质量较差，难于维 护，需要较大的测试投入和周期等问题。这些问题在一个项目组初建、需求和设计均具有不完全可预期性和完备性的全新项目中将尤为突出。可以采用以下步骤来保证和提高整个项目的代 码质量：统一编码规范、代码样式;静态代码分析(staticcodereview);单元测试;持续集成;代码评审和重构 (Review&Refactor)。4.1. 统一编码规范、代码样式规范统一的编码会增加项目代码的可读性和可维护性，但实际情况往往是项目组内的Java代码开发人员的编码风格常常各不相同，这可能是由于不同 的经验习惯或者缺乏编码规范方面的学习造成的。这样一来，其他项目成员或者维护人员在阅读项目代码时就需要花费更多的时间来理解代码作者的意图，所以制定 并采取统一的编码规范就显得很重要。编码规范主要应包含以下几个方面：一般规则