JAVA语言编码规范.doc

JAVA语言编码规范1. 简介1.1 总则本规范是翰子昂实训体系编码规范系列中的一部分。翰子昂实训体系编码规范系列包括C语言编码规范，HTML与JavaScript编码规范，JAVA编码规范，C#编码规范，ASP.NET编码规范，SQL Server编码规范，Oracle编码规范。编码规范用于提供统一编码标准，旨在指导翰子昂实训体系学生的源代码文件的规范，以保证开发团队的协作和系统的后期维护能有效进行，编码规范同时作为代码评审的依据。1.2 目的本规范提供一个JAVA语言编码的统一标准，目的在于在软件开发过程中基于JAVA语言的代码能够始终在整个开发团队中保持一致。1.3 适用范围本规范适用于翰子昂实训体系内所有应用JAVA语言的项目开发与评审活动。2. 格式2.1 缩进所有的缩进皆为4个空格。对应的括号通常在同一列的位置上。1. IDE中将一个“Tab键”设置为4个空格。2. 所有的if、while和for语句中的语句内容必须用括号括起来，就算只有一个语句。例如：#001 if (superHero = theTick)#002 System.out.println(Spoon!);#003 2.2 间隔所有的标识符都必须被空白字符包围。例如：#001 int theTick = 5; #002 if (theTick = 5) 2.3 空行1. 在逻辑代码段之间放置空行来分隔代码段；2. 在两个方法/函数/过程之间以空行来分隔；3. 在两个类或接口的定义之间放置空行来分隔；4. 包引入完毕之后放置空行。2.4 空格的位置1. 在一个关键字和左括号“(”之间。注意：不要在方法名和左括号之间加空格；2. 在参数列表的每个逗号“,”之后；3. 二元操作符前后。注意：一元操作符前后都不加空格。例如：int a = 10; a = a + 1; a+;4. for语句的每个表达式之间。例如：for (int i = 0; i 20; i+)。2.5 类成员的摆放顺序class Order1. final attributes2. attributes3. constructors4. methods必须保持private方法被放置在使用该方法的其他方法之上，而在构造器（constructor）之下，即使该构造器有可能调用这些private方法。2.6 文件格式（File Format）“package”必须总保持第一个出现；“import”其次；再次，任何非javadoc的注释；然后是javadoc类文件；最后便是类。注意：一个文件（File）只能有一个类，内部类除外。示例：#001 package misc;#002 import java.io.*;#003 import .*;#004 /* this class does cool stuff#005 * author Joe Programmer#006 * #007 */#008 class SpaceMonkey#009 #010 .#011 2.7 行最大长度不要让一行代码的长度超过120个字符，最好是低于80个字符。如果代码开始向右延伸得很长，则应该考虑把它分割成更多的方法。断行规则：1. 在逗号的后面；2. 在操作符的前面；3. 断行的起始位置应该比原行表达式的起始位置缩进4个空格。2.8 括号使用括号的目的必须是在表达上不但能够标明优先顺序，而且有助于使表达更简单明了。另外，如果某一段代码有可能产生歧义，也需加括号。3. 命名规则所有的标识符只能用字母（A-Z或a-z）和数字（0-9）。不能有货币符号或者其他非A-SCII字符。3.1 类和接口类和接口名均采用名词，首字母大写，其他单词首字母大写。例如：BufferedStreamReader缩写词必须全部大写。例如：TargetURL3.2 包1. 所有包名只能用小写字母。包名长度尽量不要超过8个字符，避免使用多个词作为包名；2. 顶级包名采用开发者所在机构的域名的逆序，若没有域名，可采用公司英文名称；例如：com.sun.jdbc、org.jboss3. 非顶级包名采用名词，或名词的缩写。3.3 方法（函数）1. 首字母小写，其他单词首字母大写，缩写词必须全部大写，例如：buildXML；2. 采用动宾结构词组。例如：createJSPPage。3.4 get和set方法用于设置对象状态的方法必须在方法名前面加一个前缀set；用于检索一个布尔类型对象状态的方法必须在方法名前面加一个前缀is；而用于检索其他类型对象状态的方法则必须在方法名前面加上get。示例：setEnabled()getName()isEnabled()3.5 变量3.5.1 普通变量：1. 变量的命名应尽可能采用有意义的名词单词，见名知义。2. 可以采用一个单词或多个单词或单词的缩写作为名字，缩写单词的每个字母都要大写。3. 对于难以使用英文的情况，可以参考相关行业标准，比如使用国标。4. 不要使用冠词。例如：anUser，thePassword，someEmps，没有必要使用冠词。但是在命名的时候，要注意名词复数，例如：users、actions。5. 采用约定俗成的习惯用法。常见的习惯用法：w 循环变量：i、j、k、m、nw 数据库：conn、stmt、pstmt、rs、rowSetw 长度：lengthw 数量：countw 位置：pos或positionw 下标或索引：indexw 设置/获取：set/getw 布尔变量的命名：isXXX，例如：isEmptySetw 大小：sizew 工具类所在的包：util3.5.2 Static Final变量（常量）的命名 Static Final 变量的名字应该都大写，每个单词之间用 “_” 连接，并且注释标明完整含义。例如：private static final int MAX_PATH = 255;3.5.3 数组数组应该总是用下面的方式来命名： byte buffer;而不是：byte buffer;3.5.4 临时变量一般临时变量没有具体的意思，所以临时变量名为：临时变量名 = 变量前缀 + （Temp或Tmp）；其中有一些C语言延续下来的常见临时变量也可以接受：如i、j、k 一般用于表示一个临时整型变量。4. 注释大部分注释尽量用“/”；对于所有的javadoc的注释则用“/* */”；而临时对代码块进行的注释尽量用“/* */”。4.1 要求1. 程序中注释行应不少程序代码行的1/3。例如，代码包括注释、空行共90行，那么注释应该不少于30行；2. 类、方法、变量必须注释说明变量如果能够自说明则可以不加注释；3. 注释内容应根据客户要求的语言进行，原则上，除常量、变量、变量类型等以外的说明尽可能采用中文注释；4. 在维护代码的同时，维护相关注释；5. 注释不要重复代码；例如：String str; /声明一个String对象：str上面的代码看上去没有问题，但是注释却是没有用的只是对代码的简单重复。注释是用来说明代码的，而不是重复代码的；6. 编写代码之前编写注释；编写注释有助于仔细的思考代码逻辑。7. 注释是用来说明要做什么，而不是如何做。4.2 JavaDoc说明1. JavaDoc注释将用于说明那些被其他类调用的类、属性和方法。这些注释必须出现在所要说明的各项之前；2. JavaDoc注释一般不会用于说明一些显而易见的方法，例如：public static void main(String args)或public int getX()；3. JavaDoc注释也不用于说明一些显而易见的参数，如：public void setX(int newX)；4. 诸如Servlet和EJB等那些没有被其他类调用的类，也不必加JavaDoc注释。把源码上交给整个团队之前，必须先经过JavaDoc处理，并全面检查处理结果，以确定说明文字确实可读而且清楚明白。注意：HTML标签和的作用。迫使一段代码进行分行，而则让块文字以特定的字体表现出来并且保留所有的空格字符。JavaDoc还允许使用其他的HTML标签，但是禁止使用header标签（如、等）可以用.加黑文字，也可以用.使文字变为斜体。JavaDoc把每个JavaDoc注释的第一行划分出来以用于放置“内容表”。如何标识出这部分内容的结束边界线呢？JavaDoc定义这个标志为“一个句号后跟一个空格”。其他如“一个问号后跟一个空格”或“一个句号后跟一个标签”都不是结束标志。如果在句号和之间加一个空格，那么就有结束标志产生了。4.3 类类的JavaDoc说明文件必须包括以下内容：1. 完成了哪些工作，即这个类是做什么的；2. 使用的方法和注意事项，如果比较难以表达，那么可以写一些示例代码；3. 作者列表；4. 当前版本和完成时间；5. 参考类，即这个类与哪些类相关。注意：类注释不要写类的实现方法，例如：“Matrix类采用主选消元法实现矩阵的求逆运算，具体算法是：”，这样的注释往往会限制类的扩展，并且加重了类的维护的工作量。我们来看一个好的类注释：#001 /*#002 * The Long class wraps a value of the primitive type#003 *long in an object.An object of type Long#004 * contains a single field whose type is long.#005 * 以上是类的作用#006 * #007 *#008 *In addition,this class provides several methods for converting a#009 * long to a String and a#010 * String to a long, as well as other#011 *constants and methods useful when dealing with along.#012 * 以上是类的使用简介#013 * author Lee Boynton#014 * author Arthur van Hoff#015 * 作者列表#016 * version 1.64, 03/21/02#017 * 版本和时间#018 */#019 public final class Long extends Number implements Comparable#020 /*代码省略*/#021 摘自SUN JDK1.4源代码，java.lang.Long4.4 方法方法的JavaDoc说明文档必须包含以下内容：1. 简要的提纲；2. 详细的描述（如果有必要在简要提纲内补充说明某些内容的话）；3. 用JavaDoc的param标签列出所有参数（如果有参数的话）；4. 用JavaDoc的return标签返回出方法的值列表（如果需要返回值的话）；5. 用JavaDoc的exception标签列出所有异常（exception）（如果有异常抛出的话）注意：方法注释也不要写算法。示例：#001 /*#002 * Executes the given SQL statement, which returns a single #003 * ResultSet object.#004 * 以上是该方法的作用#005 * param sql an SQL statement to be sent to the database,typically #006 * a static SQL SELECT statement#007 * 以上是参数说明#008 * return a ResultSet object that contains the data#009 * produced by the given query; never null#010 * 以上是返值说明#011 * exception SQLException if a database access error occurs or the #012 * given SQL statement produces anything other than a single#013 * ResultSet#013 * object#014 * 以上是异常说明#015 */#016 ResultSet executeQuery(String sql) throws SQLException;摘自SUN JDK1.4源代码，java.sql.Statement4.5 属性属性是类的状态，应该为每一个属性编写注释：说明该属性的作用，如果需要，说明其取值范围，以及使用的注意事项。例如：#001 /*#002 * The size of the ArrayList (the number of elements it contains).#003 */#004 private int size;摘自SUN JDK1.4源代码，java.uitl.ArrayList#001 /* The value is used for character storage. */#002 private char value;摘自SUN JDK1.4源代码，java.lang.String4.6 局部变量需要注释的局部变量使用行尾注释。行末注释的好处是：具有明显的针对性。例如： #001 int length = 0; /the length of the array,initial to zero.4.7 临时代码临时代码就是目前不使用的，但是也许以后会用到的代码。对于这样的代码，我们通常使用“/*/”把它们注释起来：1. 说明注释的原因。2. 说明注释者，和注释时间。3. 说明在什么情况下，可以恢复代码。4. 说明在什么情况下，这些代码需要彻底删除。5. 代码一旦正式发布，必须彻底删除这些注释。例如：/* 由于xxx原因，将以下代码注释。* 注释者：Sam Lee，时间 2006/03/04。* 只有xxx的情况下，才可继续使用下面的代码。* 如果发布之前仍未使用，则删除这些代码。 int a = 0;*/5. 编码5.1 不要使用的结构5.1.1 “dowhile”不要用dowhile循环，用while()循环。5.1.2 “return” 不要在一个方法的中间使用“return”，“return”只能出现在一个方法的末尾。原因：在方法的中间使用“return”会给重构（今后将方法拆分成几个更小的方法）带来困难；而且它会迫使开发者不得不为该方法考虑多于一个的出口点。5.1.3 “continue”绝不要用“continue”。原因：continue会给将来把一个结构拆分成几个更小的结构或方法带来许多困难；而且她也会迫使开发者不得不为该结构考虑多于一个的结束点。5.1.3 “break” “break”只能用于转换状态（switch statement）的控制。原因：在转换状态控制之外的情况下使用break，会给将来把一个结构拆分成几个更小的结构或方法带来许多困难；而且她也会迫使开发者不得不为该结构考虑多于一个的结束点。5.2 不要混合使用递增运算符和递减运算符不要混合使用递