1.   编码规范

3.1 Package的命名

Package的名字都由一个小写单词组成。单词只能由小写字母组成。

每个Package必须由：com.jutone.[project name].[module name]组成。

例如Jserver项目中：com.jutone.jserver.cpmanagement

Lottery项目中：com.jutone.lottery.sms

3.2 class和interface的命名

可以由一个或多个单词组成，每个单词的第一个字母必须大写，单词与单词之间不使用下划线连结。class和interface的单词组合后最终的意思为名词。

3.3 static final变量的命名

由一个或多个单词组成，变量的名字都大写，单词与单词之间使用下划线连结。变量的描述要完整，不允许缩写单词出现。变量的最终意思为名词。变量例如：

HIERARCHY_REQUEST_ERROR

3.4 class和interface成员变量的命名

由一个或多个单词组成，第一个单词全部小写，以后的单词的首写字母大写，单词与单词之间不使用下划线连结。变量中的单词允许缩写，缩写单词的字母都大写，不允许连续出现缩写的单词，首单词不允许缩写，缩写的单词必须在文件的开头注释中申明。变量的最终意思为名词。变量例如：

DOMString documentURL; //正确

long CPID; //错误，连续的缩写，并且首单词使用了缩写。

long contentProviderID;//正确

boolean isId;//错误，ID是缩写，因此应该用ID而不是Id，在www.w3.org中有这样的定义，但是在本公司内不采用这样的方法。

boolean isID;//正确

 

3.5 class和interface成员method的命名

由一个或多个单词组成，第一个单词全部小写，以后的单词的首写字母大写，单词与单词之间不使用下划线连结。命名中的单词允许缩写，缩写单词的字母都大写，不允许连续出现缩写的单词，首单词不允许缩写，缩写的单词必须在文件的开头注释中申明。命名的最终意思为动词。命名例如：

public void getContentsProviderID();//正确

public void getCPID();//错误，有连续的缩写。

public void getCPIdentity();//正确。

public void getContentsProviderId();//错误，ID为缩写，因此要全部大写，在www.w3.org中，这种方式被认可，但是在本公司不被认可。

3.6 在单元测试中的类命名规则

在单元测试中（动态白盒），测试类的命名方式是使用小写的test+原有的类名称。例如要测试Car类使用的测试类是testCar。

3.7在method中局部变量的命名

命名方式见3.4，为了保持一致，不特意采用匈牙利命名规范。

3.8数组的命名

byte[] buffer;

不是

byte buffer[];

2.   书写规范

4.1 javadoc的使用

// 表示注释一行，该注释不会被javadoc翻译到文档中，开发人员可以随意使用。

/*……..*/，注释若干行，该注释不会被javadoc翻译到文档中，开发人员可以随意使用。

/**…….*/，生成文档的注释，支持HTML文法。

4.1.1 class的javadoc

需要书写该类的说明，如类的描述，功能，类型，与其他类的交互等等。

/**

 * description

 */

4.1.2 attribute的javadoc

由于大部分的attribute为私有变量，所以不需要写在JAVADOC中，所以只需要用“//”来书写注释。

// description

4.1.3 method的javadoc

需要描述的有该方法的功能说明，接受的参数，返回值等等。

/**

     * The method is used for adding object.

     * @param EndUserInfo endUserInfo

     * @return int

     * success – 0

     * failed – -1

     */

4.2 文件头

/**

 * File: file name

 * Description:file description

 * @author author name

 * @version version NO.

 * Copyright: Copyright (c) 2003 Shanghai Jutone Electronics Ltd.

 */

4.3 文档中的注释

在每个类申明，类成员变量、类方法的申明前必须有文档注释。

文档注释只说明紧接其后的类、属性或方法。例如：

/** comment for class*/

public class Test

{

/**comment for an attribute*/

int number;

/**comment for a method*/

public void myMethod()

{
}

根据在文档中显示的效果，文档注释分为三部分。

4.3.1 简述

文档中，对于属性和方法都是先有一个列表，然后才在后面一个一个的详细的说明。列表中属性名或者方法名后面那段说明就是简述。例如：

/**

*[方法或属性的简述]

*/

4.3.2 详细说明

以下情况专门针对于某个方法内部。

所有的注释都在该行的上方用“//”来表示，后面接注释的内容。

 

注释的顺序为：

文件头顶格写在最上方。

空一行后写package

空一行写import

空一行写class的注释

方法的注释和上面空一行。

4.3.3 特殊部分

包括版本说明、参数说明、返回值说明等。

/**

*[方法或属性的简述]

*<p>[方法或属性的详细说明第一行]<br>

*[方法或属性的详细说明第二行]<br>

*@param […….]

*@return [……..]

*/

一些javadoc的标记

标记	用于	作用
@author	对类的说明	标明开发该类模块的作者
@version	对类的说明	标明该类模块的版本
@see	对类、属性、方法的说明	参考转向，也就是相关主题
@param	对方法的说明	对方法中某参数的说明
@return	对方法的说明	对方法返回值的说明
@exception	对方法的说明	对方法可能抛出的异常进行说明

下面详细说明各标记。

　　1. @see 的使用

　　@see 的句法有三种：

　　@see 类名

　　@see #方法名或属性名

　　@see 类名#方法名或属性名

　　类名，可以根据需要只写出类名 (如 String) 或者写出类全名 (如 java.lang.String)。那么什么时候只需要写出类名，什么时候需要写出类全名呢/em>

　　如果 java 源文件中的 import 语句包含了的类，可以只写出类名，如果没有包含，则需要写出类全名。java.lang 也已经默认被包含了。这和 javac 编译 java 源文件时的规定一样，所以可以简单的用 javac 编译来判断，源程序中 javac 能找到的类，javadoc 也一定能找到；javac 找不到的类，javadoc 也找不到，这就需要使用类全名了。

方法名或者属性名，如果是属性名，则只需要写出属性名即可；如果是方法名，则需要写出方法名以及参数类型，没有参数的方法，需要写出一对括号。如

成员类型	成员名称及参数	@see 句法
属性	number	@see number
属性	count	@see count
方法	count()	@see count()
方法	show(boolean b)	@see show(boolean)
方法	main(String[] args)	@see main(String[])

@see 的第二个句法和第三个句法都是转向方法或者属性的参考，它们有什么区别呢/em>

第二个句法中没有指出类名，则默认为当前类。所以它定义的参考，都转向本类中的属性或者方法。而第三个句法中指出了类名，则还可以转向其它类的属性或者方法。

关于 @see 标记，我们举个例说明。由于 @see 在对类说明、对属性说明、对方法说明时用法都一样，所以这里只以对类说明为例。

/**

* @see String

* @see java.lang.StringBuffer

* @see #str

* @see #str()

* @see #main(String[])

* @see Object#toString()

*/

public class TestJavaDoc

{

}

String 和 StringBuffer 都是在 java.lang 包中，由于这个包是默认导入了的，所以这两个类可以直接写类名，也可以写类全名。str、str() 为同名属性和方法，所以方法名需要用 () 区分。main 是带参数的方法，所以在 () 中指明了参数类型。toString() 虽然在本类中也有 (从 Object 继承的)，但我们是想参考 Object 类的 toString() 方法，所以使用了 Object#toString()。

　奇怪的是，为什么其中只有 str、str() 和 main(String[]) 变成了链接呢是因为编译时没有把 java.lang 包或者 Stirng、StringBuffer、Object 三个类的源文件一起加入编译，所以，生成的文档没有关于那三个类的信息，也就不可以建立链接了。

4.4 编码顺序

 

[package]

[import]

[文件头]

[一些附加说明，如缩写的表示等]

[类的注释]

[类的定义]

[类的成员变量的注释]

[类的成员变量的定义]

[类变量的存取方法的注释，指get, set]

[类变量的存取方法的定义]

[构造函数的注释]

[构造函数，参数多的写在后面，采用递增方式书写]

[克隆方法的注释]

[克隆方法的定义]

[类方法的注释]

[类方法的定义]

[类方法的实现体按照定义的顺序]

[main方法]

4.5 缩进

缩进应该是每行4个空格。不要在源文件中保存Tab字符. 在使用不同的源代码管理工具时Tab字符将因为用户设 置的不同而扩展为不同的宽度。如果你使用 UltraEdit 作为你的 Java 源代码编辑器的话，你可以通过如下操作来禁止 保存Tab字符, 方法是通 过 UltrEdit中先设定 Tab 使用的长度是4个空格，然后用Format|Tabs to Spaces 菜单将 Tab 转换为空格。

4.6 页宽

页宽应该设置为100字符。源代码一般不会超过这个宽度, 并导致无法完整显示, 但这一设置也可以灵活调整。在任何情况下, 超长的语句应该在一个逗号或者一个操作符后折行。一条语句折行后, 应该比原来的语句再缩进4个字符。

4.7 {} 对

{} 中的语句应该单独作为一行. 例如, 下面的第1行是错误的, 第2行是正确的:

if (i>0) { i ++ }; // 错误, { 和 } 在同一行

if (i>0)

{

i ++

}; // 正确, { 单独作为一行

} 语句永远单独作为一行。

如果 } 语句应该缩进到与其相对应的 { 那一行相对齐的位置。

4.8 括号

左括号和后一个字符之间不应该出现空格, 同样, 右括号和前一个字符之间也不应该出现空格. 下面的例子说明 括号和空格的错误及正确使用:

CallProc( AParameter ); // 错误

CallProc(AParameter); // 正确

不要在语句中使用无意义的括号. 括号只应该为达到某种目的而出现在源代码中。下面的例子说明错误和正确的 用法:

if ((I) = 42) { // 错误，括号毫无意义

if (I == 42 ||J == 42) // 正确，的确需要括号

4.9 程序编写规范

4.9.1 方法的程序行数

尽管不能以在每个方法中程序行数来判断代码质量的好坏，但是在大多数情况下，在一个方法实现中超过100行代码的方法多数不是质量优秀的代码，因此在本公司每个方法的实现不能超过100行。超过100行的方法需要分拆成若干个方法。

4.9.2 exit()

exit 除了在 main 中可以被调用外，其他的地方不应该调用。因为这样做不给任何代码代码机会来截获退出。一个类似后台服务地程序不应该因为某一个库模块决定了要退出就退出。

4.9.3 异常

申明的错误应该抛出一个RuntimeException或者派生的异常。

顶层的main()函数应该截获所有的异常，并且打印（或者记录在日志中）在屏幕上。

4.9.4 垃圾收集

JAVA使用成熟的后台垃圾收集技术来代替引用计数。但是这样会导致一个问题：你必须在使用完对象的实例以后 进行清场工作。比如一个perl的程序员可能这么写：

…

{

FileOutputStream fos = new FileOutputStream(projectFile);

project.save(fos, “IDE Project File”);

}

…

除非输出流一出作用域就关闭，非引用计数的程序语言，比如JAVA，是不能自动完成变量的清场工作的。必须象下面一样写：

FileOutputStream fos = new FileOutputStream(projectFile);

project.save(fos, “IDE Project File”);

fos.close();

4.9.5 Clone

下面是一种有用的方法：

implements Cloneable

public

Object clone()

{

try

{

ThisClass obj = (ThisClass)super.clone();

obj.field1 = (int[])field1.clone();

obj.field2 = field2;

return obj;

} catch(CloneNotSupportedException e)

{

throw new InternalError(“Unexpected CloneNotSUpportedException: ” + e.getMessage());

}

}

4.9.6 final 类

绝对不要因为性能的原因将类定义为 final 的（除非程序的框架要求）

如果一个类还没有准备好被继承，最好在类文档中注明，而不要将她定义为 final 的。这是因为没有人可以保 证会不会由于什么原因需要继承她。

4.9.7 访问类的成员变量

大部分的类成员变量应该定义为 private 的来防止继承类使用他们。

注意，要用“int[] packets”，而不是“int packets[]”，后一种永远也不要用。来源：huaiyuren