JAVA编码规范-V1.0.doc

JAVA编程规范软通动力公司JAVA编程规范编号：ISS-STD-JAVA版本:1.0变更记录日期版本变更说明作者2012626在软通编码规范基础上修改李博宇、包维、李强、张本晨、沙丽沄20120712在软通编码规范基础上修改李博宇、包维、李强、张本晨、沙丽沄20120713在软通编码规范基础上修改李博宇、包维、李强、张本晨、沙丽沄目录1导言51.1目的51.2范围51.3角色和职责51.4术语定义52格 式62.1.缩进62.2间隔72.3空行82.4类成员的摆放顺序82.5文件格式(File Format)82.6行最大长度92.7括号93命名规则103.1类和接口103.2包103.3get和set方法（属性的定义）103.4变量113.4.1普通变量：113.4.2常用对象变量113.4.3Static Final变量的命名113.4.4临时变量114注 释124.1要求124.2JavaDoc说明124.3类134.4方法144.5代码的自我说明155编 码165.1不要使用的结构165.1.1“dowhile”165.1.2return (建议，尽量避免，也可以使用)165.1.3continue165.1.4break165.2不要混合使用递增运算符和递减运算符165.3变量初始化175.4魔鬼数字/字符175.5范围（scope）171 导言Java语言给了程序员充分的空间随意编写自己的代码，但也正是因为如此，一个程序员自己编写的代码往往不能被别的程序员很好的阅读和理解。1.1 目的本文档旨在提供一个编码的标准，以便所有Java代码在产生的一开始就能够在整个开发团队中保持一致，从而能够更好的阅读和修改代码。1.2 范围本文档适用于软通动力公司项目开发团队的所有成员，为了使项目的后期维护和修改变的容易，在每个项目开发中一定要遵守本文档中的规定术语定义1.3 角色和职责l 编码负责人：本规范在具体项目中执行监督负责人。通过实施Source Review 制度，编程人员在完成自己的一个模块并提交测试前，由编码负责人进行Source Review，不符合本编程规约的程序一律打回，重新修改，即编码人你认为自己的程序没有任何的功能问题。l 编码人员本规范的遵守者。1.4 术语定义l Logger - 系统进行日志输出了类，为引用第三方（Apache Group）的输出类，具体用法见 Log输出规范的说明。2 格 式2.1 .缩进所有的缩进皆为4个空格。对应的括号通常在同一列的位置上。例如： void foo() while ( bar 0 ) Logger.debug(); bar- ; if ( oatmeal = tasty ) Logger.debug(Oatmeal is good and good for you); else if ( oatmeal = yak ) Logger.debug(Oatmeal tastes like sawdust); else Logger.debug(tell me pleeze what iz dis oatmeal); switch( suckFactor ) case 1: Logger.debug(This sucks); break; case 2: Logger.debug(This really sucks); break; default: Logger.debug(whatever); break; 1）所有的缩进是由Space(空格)键形成的，而不是Tab键。2）所有的if、while和for语句中的状态内容必须用括号括起来，就算只有一个状态。if ( superHero = theTick ) Logger.debug(Spoon!);2.2间隔1）所有的标识符都必须被空白字符包围。 int theTick = 5 ; if ( theTick = 5 ) 这么做唯一可能成为麻烦的是复杂的布尔分析影响了清晰度，例： if ( ( hero = theTick ) & ( ( sidekick = arthur ) | ( sidekick = speak ) ) )不如这样： boolean isTickSidekick = ( ( sidekick = arthur ) | ( sidekick = speak ) );if ( ( hero = theTick ) & isTickSidekick ) 2）然而也有一些例外的情况，见下表：例 外 情 况原 由正 确 示 例错 误 示 例方 法 名习惯写法是在所有方法名之后直接跟上一个左括号foo( i ) ;start() ;args 0 ;tens i ;数 组习惯写法是在所有数组名之后直接跟上一个左方括号args0 ;tens I ;args 0 ;tens i ;自加、自减运算符习惯写法是在所有一元运算符前面或后面直接加上操作数+count ; i- ;+count ; i - ;造型运算符习惯写法是所有造型都不加空格(MyClass)v.get( 3 ) ;(MyClass) v.get( 3 ) ;( MyClass )v.get( 3 ) ;2.3空行应该时不时的在各方法之间加入一些空格行来分割大段的代码；还应该在方法与方法之间加入一两行的空格行。2.4类成员的摆放顺序 class Order 1. final attributes2. attributes3. constructors4. methods 必须保持private方法被放置在使用该方法的其他方法之上，而在构造器（constructor）之下，即使该构造器有可能调用这些private方法。2.5文件格式(File Format)package必须总保持第一个出现；import其次；再次，任何非javadoc的注释；然后是javadoc类文件最后便是类。注意：一个文件(File)只能有一个类，内部类除外。示例： package misc ; import java.io.* ; import .* ; /* this class does cool stuff * author Joe Programmer */ class SpaceMonkey . 2.6行最大长度不要让一行代码的长度超过120个字符，最好是低于80个字符。如果代码开始向右延伸得很长，你就应该考虑把它分割成更多的方法。2.7括号使用括号的目的必须是在表达上不但能够标明优先顺序，而且有助于使表达更简单明了。另外，如果某一段代码有可能产生歧义，也需加括号。3 命名规则所有的标识符只能用字母（A-Z或a-z）和数字（0-9）。不能有货币符号或者其它非ASCII字符，尽量少用数字。3.1 类和接口所有类和接口标识符将都使用混合格表示。每个名称中的每个单词首字母必须大写，同时这个名称的首字母也必须大写；其它的字母均小写，除了缩写词之外（它们必须全部大写）。示例： CustomerSalesOrderTargetURLURLTarget3.2 包所有包名只能用小写字母。尽量别使包名长度超过8个字符，应该避免使用多个词作为包名。示例：commoncorelang3.3 get和set方法（属性的定义）使用Eclipse的自动代码生成get和set方法。变量不要使用前缀，变量的类型在名称后面表示，如：SystemDate，后面表示类型。以免生成的方法不方便使用。3.4 变量3.4.1 普通变量：变量的命名应尽可能采用见名知义，基本命名规则如下：变量名 = 变量含义 （+ 变量后缀）后缀不一定要使用变量后缀遵循规则，定义如下：3.4.2 常用对象变量类型前缀VectorvHashMaphmHashtablehtDateDateTimestampTimeCollectioncollIteratoritListLObjectaryObj3.4.3 Static Final变量的命名 Static Final 变量的名字应该都大写，每个单词之间用 ”_” 连接，并且指出完整含义。3.4.4 临时变量一般临时变量没有具体的意思，所以临时变量名为：临时变量名 = 变量前缀 + （Temp或Tmp）；其中有一些C语言延续下来的常见临时变量也可以接受：如i , j , k 一般用于表示一个临时整型变量。4 注 释大部分注释尽量用/；对于所有的javadoc的注释则用/* */；而临时对代码块进行的注释尽量用/* */。使用时在Eclipse中输入/*，回车即可自动生成JavaDoc的注释格式。4.1 要求1、 程序中注释行应不少程序代码行的40%；2、 类、方法、变量必须注释说明；3、 注释内容应根据客户要求的语言进行，原则上，除常量、变量、变量类型等以外的说明尽可能采用中文注释；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处理，并全面检查处理结果，以确定说明文字确实可读而且清楚明白。如果JavaDoc注释能够在一行内写下，则格式应该象下面这样： /* Used to mark spots */ int x ;如果JavaDoc注释内容在一行内容纳不下，则其格式应该象下面这样： /* Set how much to grow when growth is needed. * Smaller values will usually save memory, but frequent * reallocation may take a lot of time. * param HowMuch The number of extra ints to allocate when * memory reallocation is required. Values must be greater than * zero. */ public void setExtra( int HowMuch )注意：HTML标签和的作用。迫使一段代码进行分行，而则让块文字以特定的字体表现出来并且保留所有的空格字符。JavaDoc还允许使用其它的HTML标签，但是禁止使用header标签（如, 等）你可以用.加黑文字，也可以用.使文字变为斜体。注意：JavaDoc把每个JavaDoc注释的第一行划分出来以用于放置内容表。如何标识出这部分内容的结束边界线呢？JavaDoc定义这个标志为一个句号后跟一个空格。其它如一个问号后跟一个空格或一个句号后跟一个标签都不是结束标志。如果在句号和之间加一个空格，那么就有结束标志产生了。4.3 类类的JavaDoc说明文件必须包括以下内容：（1）简要的提纲（2）详细的描述（3）使用该类的示例代码段（4）用author标签列出作者注意：由于JavaDoc中一个功能（feature）限制，所有示例代码的每行前面必须加入一个星号，以便保存每行的缩进。例如： /* A vector class optimized for working with ints. * Like the Vector object, except rather than tracking a dynamic * array of pointers to different objects, this is simply a * dynamic array of ints. The advantage is speed and memory * savings. * Example: * * / report longest lines * TextFileIn f = new TextFileIn(blather.txt); * IntVector v = new IntVector(); * int longestLine = 0 ; * boolean done = false ; * while ( ! done ) * * String s = f.readLine(); * if ( s = null ) * * done = true ; * * else * * int sLength = s.length() ; * if ( sLength longestLine ) * * longestLine = sLength ; * * v.append( sLength ); * * * f.close(); * Logger.debug(The longest lines are on line numbers:); * for ( int i = 0 ; i v.length() ; i+ ) * * if ( v.get( i ) = longestLine ) * * Logger.debug( i ); * * * * author Adam Baum * author Justin Case */ public class IntVector4.4 方法方法的JavaDoc说明文档必须包含以下内容：（1）简要的提纲；（2）详细的描述（如果有必要在简要提纲内补充说明某些内容的话）；（3）用JavaDoc的param标签列出所有参数（如果有参数的话）；（4）用JavaDoc的return标签返回出方法的值列表（如果需要返回值的话）；（5）用JavaDoc的exception标签列出所有异常（exception）(如果有异常抛出的话)示例： /* Get a copy of one int. * Retrieve an int relative to the index provided. * param Index Which int (0 is the first int). * return The retrieved int or zero if Index is outside of 0.length. */ public int get( int Index )4.5 代码的自我说明傻子写计算机识别的程序；程序员写人识别的程序。 -Martin Fowler, Refactoring：提高代码的设计水平除了要尽力用文件说明程序的复杂算法，我们还必须尽量通过多用一些标识符来使程序的算法易读。这样有助于减少将来需要修改程序而不需修改说明文档而带来的麻烦。 /* determine if the given year is a leap year. * The Gregorian calendar principal states that a leap year occurs * every fourth year, except every 100 years, except every 400 * years. * param year The year to be tested. Make sure this is a four digit year! * return true if year is a leap year. */ boolean isLeapYear( int year ) boolean y4 = ( ( year % 4 ) = 0 ) ; boolean y100 = ( ( year % 100 ) = 0 ) ; boolean y400 = ( ( year % 400 ) = 0 ) ; return ( y400 | ( y4 & ! y100 ) ); 5 编 码5.1 不要使用的结构5.1.1 “dowhile” 不要用dowhile循环,用while()循环5.1.2 return (建议，尽量避免，也可以使用)不要在一个方法的中间使用return，return只能出现在一个方法的末尾。原因：在方法的中间使用return会给今后将方法拆分成几个更小的方法带来困难；而且它会迫使开发者不得不为该方法考虑多于一个的出口点。5.1.3 continue决不要用continue。原因：c