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