Java代码书写规范

一、通用规范

1.1命名规范

1. 使用全单词表示

2. 使用贴切的词汇

3. 使用大小写混合

4. 尽量少用缩略词，否则，维护一个标准的缩略词表

5. 避免过长，小于15

6. 避免类似的命名或仅在大小写上区分的命名

7. 标准缩略词做一个单词处理

1.2文档规范

1. 增加注释，以确保代码清晰

2. 无需注释的程序，可能也不值得运行

3. 避免修饰性注释

4. 保持注释简洁

5. 写代码之前写注释

6. 注释中说明代码的原因，而不是结果

二、Java编码规范

2.1命名和大小写规范：

下面这些广泛使用的命名规范可以应用到Java中的包、类、方法、属性和常量。因为这些规范的使用非常普遍，而且它们还影响到了我们定义的类的公共API，所以我们应该认真遵守这些规范：

1. 包

   保证包的名称是唯一的，包的名称前缀以我们的网络域名称，包名小写（例如com.itsv.utils）置于文件最上一行

2. 类

   第一个字母必须大写，所以类名称是大小写混合的（例如String）；如果类名称是由多个单词组成的，那么每个单词都应该以大写字母开头（例如StringBuffer）；如果一个类名称或者类名称中的一个单词是字母缩写词，那么我们可以把这个缩写词中的每个字母都写成大写（例如URL、HTMLParser）。因为设计的类是用来代表对象的，所以我们在为类起名称时应尽量选择名词。

   如果是某一种特殊类别的类，则可以统一采用特殊简短后缀来标识，这些后缀全部大写。例如，对所有处理与数据库相关的类，可以在类名后加上DAOImpl来标识

引用类： 全部置于包名之后，文件所定义类名之前

类的定义顺序：

class xxx

constructors

finalize

public member functions

protected member functions

private member functions

private fields

3. 接口

   接口名称遵循的大小写规则和类名称是一样的。用接口来提供一些关于实现它的类的额外信息，常用形容词作为接口名称（例如Runnable），当接口更像一个抽象的超类时，我们又用名词来作为接口的名称（例如Document）

在创建类之前先创建公共接口，以确定类的应用存根，接口的命名用描述性的形容词或名词，或者加前缀I 或后缀Ifc：

Runnable

Cloneable

Singleton

DataInput

4. 方法

   方法名称总是以小写字母开头。如果名称中包含的单词多于一个（一般使用动词和名词组合而成），那么除第一个单词外的所有单词都应该以大写字母开头，动词放在首单词，例如insert（）、insertObject（）。

成员变量访问方法accessor的命名：

使用Getter-get和Setter-set方法，对于boolean类型的可以使用is代替get

Getter还有can和has

成员方法的范围：

范围	描述	正确使用方法
Public	任何类或对象的任何成员方法中可以调用	当该方法必须被当前类分支之外的类或对象调用时
Protected	只能被同类及所有子类的成员方法调用	当该方法只能被当前类及其分支之内的类或对象调用时
private	只能被同类的成员方法调用，子类的成员方法不能调用	封装一个类的特有方法，当前类所特有，其他类或子类没有
	缺省的为软件包级可用，对相同软件包package的类可使用，不能在不同软件包的类中调用

5. 属性和常量

   非常量的属性名称所遵循的大小写规则和方法名称是一样的。如果一个属性是静态final类型的常量，那么该属性的所有字母都应该大写。如果常量的名称中包含多个单词，那么应该用下划线来分隔这些单词（例如MAX_VALUE）。此外，选择的属性名称应该是最能说明属性或其取值的含义的。

集合属性(Array, Vector)采用复数

firstName

orderItems

常量命名

static final MAX_VALUE

属性范围

范围	描述	用于
public	可以在所有类的方法中引用	最好不定义此类属性
protected	可以在本类及子类方法中引用	最好不定义此类属性
private	只能用于同类的方法中	所有属性都应是此种类型并通过访问器accessor访问

6. 参数

   方法参数名称会出现在方法的文档中，所以参数含义应尽可能明确。一般参数名称为一个单词。

成员函数的参数标准：

使用接口代替类作为参数，实现多态性

7. 局部变量

   命名规则和方法以及属性的命名规则一样。

2.2 注释规范

2.2.1总体说明

1. 三种类型的Java注释

注释类型	用于	例子
文档注释	写在类、接口、成员函数和属性的定义紧前方，由javadoc用于创建类的外部文档。	/**  * document comments  */
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标签，它定义了出现在注释中的第二张图片：<IMG src=”doc-files/Circles-2.gif”> 

2.2.2具体注释内容

1. 注释类

类功能说明：注释类的功能

@author 注释类的作者

@see  注释引用类的情况

@version 注释类的版本信息

2. 注释成员方法

l 头部注释

1. 功能描述：描述成员方法的功能及存在的原因（必填）

2. @param 参数及名称描述（必填）

3. @return 返回值（必填）

4. @exception 描述信息

5. @see 引用说明

6. @since 版本号

7. 存在问题：存在的尚未解决的问题

8. 使用范围：确定使用范围及原因

9. 外部变动：对其他对象的变动注释

10. 修改历史：注明修改时间、修改人、修改内容、修改原因（必填）

11. 调用方法：说明调用的前提条件和事后条件、说明并发调用情况

l 内部注释

1. 在方法内部的开始部分统一注释方法的逻辑

2. 控制结构，结构性语句的起始位置需要注明，控制结构的尾部

3. 注明局部变量

4. 注释结束括号}

2.3编写清晰的代码

1. 注释文档

2. 段落化

3. 多行语句段落化

4. 使用空格和空行

5. 方法不能太长，遵循30秒规则

6. 定义消息的传递，在注释中体现

7. 简短的命令行

8. 将比较的常数放在左方，以防止误写为赋值语句

三、 JAVA命名缩略词表

参见缩略词表。