Java编码规范.docx

Java编码规范.docx

《Java编码规范.docx》由会员分享，可在线阅读，更多相关《Java编码规范.docx（22页珍藏版）》请在冰豆网上搜索。

Java编码规范

目录

1、规范说明2

1．1）文档状态2

1．2）规范简介2

2、命名规则2

2．1）一般的命名规则2

2．2）标识符命名2

3、文档注释4

3．1）注释原则4

3．2）注释类型表5

3．3）注释规则表5

3．4）Javadoc规则6

4、JAVA文件样式7

5、代码编写格式11

6、程序规范13

6．1）保证程序的健壮性（必须做的）13

6．2）提高代码效率的做法（尽量做的）16

6．3）其他要注意的做法（推荐做的）17

7、JSP补充规范19

7．1）程序代码规范19

7．2）文件命名和路径存放19

7．3）编码注意事项20

8、日志和调试信息20

8．1）为什么要使用调试信息和日志20

8．2）使用Log4j进行日志操作20

1、规范说明

1．1）文档状态

本版本：

Version1.0Java编码规范.doc

分发：

公司研发部可以不受任何限制地分发

1．2）规范简介

简介：

本标准描述了所有基本Java编程应该遵循的规范，涉及到命名规则、代码格式及编程规则（建议）。

这里“基本Java编程”指的是编写JavaBeans，Applet，Application，Servlet，JSP，EJB中的Class，Interface等。

相应的辅助编程标准（如：

EJB编程规范）请阅读其它编程标准。

为什么要制定规范？

所有的程序开发手册都包含了各种规则。

一些习惯自由程序人员可能对这些规则很不适应，但是在多个开发人员共同写作的情况下，这些规则是必需的。

这不仅仅是为了开发效率来考虑，而且也是为了后期维护考虑。

定义这个规范的目的是让项目中所有的文档都看起来像一个人写的，增加可读性，减少项目组中因为换人而带来的损失。

（这些规范并不是一定要绝对遵守，但是一定要让程序有良好的可读性）

适用范围：

本规范使用公司内部使用Java语言进行开发的过程。

如果本规范内容和Java语法（或者Java语言发布者的规范）冲突，则已后者为准。

2、命名规则

2．1）一般的命名规则

●使用完整的英文描述符

●采用适用于该领域的术语

●采用大小写混合使名字可读

●尽量少用缩写，但如果用了，要明智地使用。

●避免使用长的名字（小于15个字母是个好主意）

●避免使用类似的名字，或者仅仅是大小写不同的名字

●尽管Java语言没有限制，但是名称中几乎不使用$符号和下划线，因为常量使用所有的大写字母，并且将下划线作为单词分隔符使用，如：

MY_CONSTANT。

避免使用类似temp1，temp2，temp3这样的名称，它们不能代表任何特征。

2．2）标识符命名

操作项

命名约定

示例

包

一个唯一包名的前缀总是全部小写的ASCII字母并且是一个顶级域名，通常是com，edu，gov，mil，net，org，或1981年ISO3166标准所指定的标识国家的英文双字符代码。

包名的后续部分根据不同机构各自内部的命名规范而不尽相同。

这类命名规范可能以特定目录名的组成来区分部门（department），项目（project），机器（machine），或注册名（loginnames）。

✓内部建议格式：

“域后缀”+“.”+“公司标识”+“.”+“工程名”+“.”+“功能模块”+“.”+“子模块”+….

如com.sme.baseframe.control

类名

命名规则：

类名是个一名词，采用大小写混合的方式，每个单词的首字母大写。

尽量使你的类名简洁而富于描述。

使用完整单词，避免缩写词（除非该缩写词被更广泛使用，像URL，HTML）

MyClass

接口

接口名称与类方法的命名惯例相同。

习惯上，名字前面加上前缀来表示它的类型。

InRunnabl，AbLayoutManager

Factory类

符合AbstructFactory设计模式的类名称后面添加第一个字母大写的单词“Factory”。

PreambleFactory

Servlet类

从HttpServlet派生的普通类：

按普通类命名后在加上Service

从HttpServlet派生并实现Filter的类：

按普通类命名后加上Filter

从HttpServlet派生并实现ServletContextListener,ServletContextAttributeListener,HttpSessionListener,HttpSessionAttributeListener的类：

按普通类命名后加上Listener

LoginService.java

RegisterService.java

WebSiteFilter.java

AuthorizationFilter.java

AddCategoryEventListener.java

AddPropertyEventListener.java

Struts类

从ActionForm派生的类：

按普通类命名后加上Form.

从Action派生的类：

按普通类命名后加上Action

SignInForm.java

ViewProductAction.java

Applet

从java.applet.Applet派生的类：

按普通类命名后加上Applet

CatalogtreeApplet.java

类方法

类方法的名称混合使用大小写字母，第一个字母小写，但是后续每个新单词的首字母大写。

整个单词混合大小写，通常是单词组合。

类方法名称的第一个单词常常采用一个有强烈动作色彩的动词。

可加前缀表示返回类型.

openFile（）,voName（）

静态方法

静态方法名称与类方法的命名惯例相同。

main

构造方法

构造方法与它所属类的名字总是相同的。

析构方法

Java没有析构函数，但一个对象在垃圾收集时，调用成员函数finalize（）。

finalize

设置方法

使用全部小写的单词“set”开始。

setPortOn

普通获取方法

使用全部小写的单词“get”开始。

getPrivatePhone

返回布尔值的获取函数

使用单词“is”、“has”或者“can”开始

IsValidListener，canGenerateText，hasMoreElement

实现方法

实现方法的名称使用“make”开始。

makeToDoList

调试方法

只作调试用的代码片段的特殊名称以“debug”开始。

debugMyMethod

属性

采用完整的英文描述，第一个字母小写，任何中间单词的首字母大写。

尽量避免使用超类中已经使用的属性名称，容易引起错误。

firstName，lastName，warpSpeed

常量

常量（final）名称全部是用大写字母并在单词之间添加下划线。

MY_CONSTANT

组件

使用完整的英文描述来说明组件的用途，末端应接上组件类型。

okButton，fileMenu

局部变量

采用完整的英文描述符，第一个字母小写，但不要和已有属性同名。

如果有一个字段叫firstName，不要让一个局部变量叫firstName。

firstName

参数

每个参数多数情况下是单词组合，而且每个单词首字母小写，单词的其余部分混合使用大小写。

account

异常

通常采用能够表达其意义的小写字母组合来表示。

SQLException–sqle，IllegalStateException–ise

循环计数器

通常采用字母I，j，k或者index，counter都可以接受。

ijkindexcounter

3、文档注释

3．1）注释原则

●每份代码中都需要全部三类注释：

即文件说明、方法说明、变量说明。

分别位与每个接口、类和方法的开头部分，由Javadoc（/**）注释组成。

●几乎所有申明单行注释（//），解释申明项的目的。

在循环体中申明的循环计数器是个例外。

●实际使用时，单行注释应该垂直对齐。

●注释通常位于其主题前面。

在这类注释前添加一空白行，但是不要在后面添加空白行。

●注释生成的javadocHTML文档应该写得足够清楚，尽管很少有人需要读懂代码。

●通常需要包括公司标准的版本标志。

●根据公司实际状况，注释采用中文，但不反对同时用英文注释，但要保证语意正确。

●利用注释将代码组合到一起，例如将所有I/O方法组合在程序的某个区域，除非如此处理会将的代码的可读性，保持注释的简洁。

●除了第一行外，所有注释块（/*）或者javadoc（/**）中的每一行都应该以星号（*）开始。

●如果巧妙的代码无法简化，则需要使用注释解释，注释应该增加代码的清晰度。

●注释永远不能代替或者解释一个恰当地描述型变量名称或者方法名称。

●首要准则：

编写注释是当作要在杂志上发表的文章一样重视。

如果你的程序不值得注释，那么它也很可能不值得运行。

●全部注释应该占代码的约20%左右，在写代码之前写注释。

●注释出为什么做了一些事，而不仅仅是做了什么。

3．2）注释类型表

注释类型

用法

示例

javadoc注释

在紧靠接口、类、成员函数和字段声明的前面注释它们。

注释语句由javadoc处理，为一个类生成外部文档参见下文。

/**

客户：

客户是我们将服务和产品卖给的人或机构。

@authorKen.Zhou

*/

C语言风格

采用C语言风格的注释去掉不再使用但你仍想保留的代码。

仍想保留是因为用户万一会改变想法，或者在调试过程中想让它暂时失效。

/*

这部分代码因为已被它之前的代码取代，由B.Gustafsson,于1999年6月4日注释掉。

如果两年之后还未使用，将其删除。

...（源代码）

*/

单行注释

在成员函数内采用单行注释，来说明业务逻辑、代码段和暂时变量的声明。

//遵照Sarek的规定，给所有

//超过$1000的发货单

//打5%的折扣。

让利活

//动于1995年2月开始.

3．3）注释规则表

下表概括了所写Java代码中的每一部分哪些需要注释说明。

项目

注释哪些部分

包

包的基本原理

包中的类

类

类的目的

已知的问题

类的开发/维护历史

注释出采用的常量

并行策略

接口

目的

它应如何被使用以及如何不被使用

Factory类

参照类注释，并指明创建的产品对象

类方法

类方法做什么以及它为什么做这个

哪些参数必须传递给一个类方法

类方法返回什么

已知的问题

任何由某个成员函数抛出的异常

可见性决策

类方法是如何改变对象的

包含任何修改代码的历史

如何在适当情况下调用类方法的例子

适用的前提条件和后置条件

类方法内部注释

控制结构

代码做了些什么以及为什么这样做

局部变量

难或复杂的代码

处理顺序

静态方法

参照类方法注释

属性

属性描述

注释所有使用的常量

示例

并行事件

可见性决策

参数

参数类型

参数用来做什么

任何约束或前提条件

示例

异常

参照类注释，并指明异常抛出的原因

3．4）Javadoc规则

Sun公司的JavaDevelopmentKit（JDK）中有一个名为javadoc的程序。

它可以处理Java的源代码文件，并且为Java程序产生HTML文件形式的外部注释文档。

Javadoc支持一定数目的标记，标识注释文档中各段起始位置的保留字。

详情请参考J