Java代码书写规范

Java代码书写规范2003/04/15当不得不违背本规范时，请详细注释原因一、通用规范1.1命名规范1.使用全单词表示2.使用贴切的词汇3.使用大小写混合4.尽量少用缩略词，否则，维护一个标准的缩略词表5.避免过长，小于156.避免类似的命名或仅在大小写上区分的命名7.标准缩略词做一个单词处理1.2文档规范1.增加注释，以确保代码清晰2.无需注释的程序，可能也不值得运行3.避免修饰性注释4.保持注释简洁5.写代码之前写注释6.注释中说明代码的原因，而不是结果二、Java编码规范2.1命名和大小写规范：下面这些广泛使用的命名规范可以应用到Java中的包、类、方法、属性和常量。因为这些规范的使用非常普遍，而且它们还影响到了我们定义的类的公共API，所以我们应该认真遵守这些规范：1.包保证包的名称是唯一的，包的名称前缀以我们的网络域名称，包名小写（例如com.itsv.utils）置于文件最上一行2.类第一个字母必须大写，所以类名称是大小写混合的（例如String）；如果类名称是由多个单词组成的，那么每个单词都应该以大写字母开头（例如StringBuffer）；如果一个类名称或者类名称中的一个单词是字母缩写词，那么我们可以把这个缩写词中的每个字母都写成大写（例如URL、HTMLParser）。因为设计的类是用来代表对象的，所以我们在为类起名称时应尽量选择名词。如果是某一种特殊类别的类，则可以统一采用特殊简短后缀来标识，这些后缀全部大写。例如，对所有处理与数据库相关的类，可以在类名后加上DAOImpl来标识引用类：全部置于包名之后，文件所定义类名之前类的定义顺序：classxxxconstructorsfinalizepublicmemberfunctionsprotectedmemberfunctionsprivatememberfunctionsprivatefields3.接口接口名称遵循的大小写规则和类名称是一样的。用接口来提供一些关于实现它的类的额外信息，常用形容词作为接口名称（例如Runnable），当接口更像一个抽象的超类时，我们又用名词来作为接口的名称（例如Document）在创建类之前先创建公共接口，以确定类的应用存根，接口的命名用描述性的形容词或名词，或者加前缀I或后缀Ifc：RunnableCloneableSingletonDataInput4.方法方法名称总是以小写字母开头。如果名称中包含的单词多于一个（一般使用动词和名词组合而成），那么除第一个单词外的所有单词都应该以大写字母开头，动词放在首单词，例如insert（）、insertObject（）。成员变量访问方法accessor的命名：使用Getter-get和Setter-set方法，对于boolean类型的可以使用is代替getGetter还有can和has成员方法的范围：范围描述正确使用方法Public任何类或对象的任何成员方法中可以调用当该方法必须被当前类分支之外的类或对象调用时Protected只能被同类及所有子类的成员方法调用当该方法只能被当前类及其分支之内的类或对象调用时private只能被同类的成员方法调用，子类的成员方法不能调用封装一个类的特有方法，当前类所特有，其他类或子类没有缺省的为软件包级可用，对相同软件包package的类可使用，不能在不同软件包的类中调用5.属性和常量非常量的属性名称所遵循的大小写规则和方法名称是一样的。如果一个属性是静态final类型的常量，那么该属性的所有字母都应该大写。如果常量的名称中包含多个单词，那么应该用下划线来分隔这些单词（例如MAX_VALUE）。此外，选择的属性名称应该是最能说明属性或其取值的含义的。集合属性(Array,Vector)采用复数firstNameorderItems常量命名staticfinalMAX_VALUE属性范围范围描述用于public可以在所有类的方法中引用最好不定义此类属性protected可以在本类及子类方法中引用最好不定义此类属性private只能用于同类的方法中所有属性都应是此种类型并通过访问器accessor访问6.参数方法参数名称会出现在方法的文档中，所以参数含义应尽可能明确。一般参数名称为一个单词。成员函数的参数标准：使用接口代替类作为参数，实现多态性7.局部变量命名规则和方法以及属性的命名规则一样。2.2注释规范2.2.1总体说明1.三种类型的Java注释注释类型用于例子文档注释写在类、接口、成员函数和属性的定义紧前方，由javadoc用于创建类的外部文/***documentcomments*/档。C风格注释暂时注释不用的代码/*comments*/单行注释在成员函数中用于注释商业逻辑，代码段，变量定义//comments文档注释的主体部分一开始应该先用一句话概括类、接口、方法或属性完成的功能，书写时单独占一行。概括性句子的后面还可以跟若干条,详细介绍类、接口、方法或属性的注释语句及段落。在描述性的段落之后，文档注释还可以包括其他一些段落，每个段落都以一个特殊的文档注释标签开始，例如@auther、@param。2.doc注释的标签@author名称后加上相应的作者@version文本插入指定文本的版本信息@param参数-名称描述@return描述@exception完整的类名称描述信息@throws完整的类名称描述信息@see引用其他类，格式如下：@see类名@see完整类名@see完整类名#方法名{@link引用}@deprecated解释@since版本号@serial描述信息@serialField名称类型描述信息@serialData描述信息@beaninfo信息文档注释的描述信息可以包括简单的HTML标注标签，不包括HTML的主要结构标签，例如H2和HR等。在文档注释中使用标签{@link}来引用超级链接或者是交叉引用，避免用标签A。如果希望在文档注释中包括图像，可以把图像文件放在源代码目录下的doc文件的子目录中，然后把图像取名为和类一样的名称，并在名称之后加上数字作为后缀，例如，可以在叫做Circle类的文档注释中包括下面这个HTML标签，它定义了出现在注释中的第二张图片：IMGsrc=”doc-files/Circles-2.gif”2.2.2具体注释内容1.注释类类功能说明：注释类的功能@author注释类的作者@see注释引用类的情况@version注释类的版本信息2.注释成员方法头部注释1.功能描述：描述成员方法的功能及存在的原因（必填）2.@param参数及名称描述（必填）3.@return返回值（必填）4.@exception描述信息5.@see引用说明6.@since版本号7.存在问题：存在的尚未解决的问题8.使用范围：确定使用范围及原因9.外部变动：对其他对象的变动注释10.修改历史：注明修改时间、修改人、修改内容、修改原因（必填）11.调用方法：说明调用的前提条件和事后条件、说明并发调用情况内部注释1.在方法内部的开始部分统一注释方法的逻辑2.控制结构，结构性语句的起始位置需要注明，控制结构的尾部3.注明局部变量4.注释结束括号}2.3编写清晰的代码1.注释文档2.段落化3.多行语句段落化4.使用空格和空行5.方法不能太长，遵循30秒规则6.定义消息的传递，在注释中体现7.简短的命令行8.将比较的常数放在左方，以防止误写为赋值语句三、JAVA命名缩略词表参见缩略词表。