Java 编程规范

时间 2019-12-04

标签 java 编程规范栏目 Java 繁體版

原文原文链接

Java 编程规范 html

排版java

规则node

程序块要采用缩进风格编写，缩进的空格数为4个，不容许使用TAB缩进。(1.42+)程序员

说明：缩进使程序更易阅读，使用空格缩进能够适应不一样操做系统与不一样开发工具。web

分界符（如大括号‘{’和‘}’）应各独占一行，同时与引用它们的语句左对齐。在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序或者static、,synchronized等语句块中都要采用如上的缩进方式。(1.42+)算法

示例:数据库

if (a>b)编程

{数组

doStart();app

}

较长的语句、表达式或参数（>80字符）要分红多行书写，长表达式要在低优先级操做符处划分新行，操做符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。(1.42+)

示例：

if (logger.isDebugEnabled())

{

logger.debug("Session destroyed,call-id"

+ event.getSession().getCallId());

}

不容许把多个短语句写在一行中，即一行只写一条语句(1.42+)

说明：阅读代码更加清晰

示例：以下例子不符合规范。

Object o = new Object(); Object b = null;

if, for, do, while, case, switch, default 等语句自占一行，且if, for, do, while,switch等语句的执行语句不管多少都要加括号{},case 的执行语句中若是定义变量必须加括号{}。(1.42+)

说明：阅读代码更加清晰，减小错误产生

示例：

if (a>b)

{

doStart();

}

case x:

{

int i = 9;

}

相对独立的程序块之间、变量说明以后必须加空行。 (1.42+)

说明:阅读代码更加清晰

示例：

if(a > b)

{

doStart();

}

//此处是空行

return;

在两个以上的关键字、变量、常量进行对等操做时，它们之间的操做符以前、以后或者先后要加空格；进行非对等操做时，若是是关系密切的当即操做符（如.），后不该加空格。(1.42+)

说明：阅读代码更加清晰

示例：

if (a == b)

{

objectA.doStart();

}

a *= 2;

建议

类属性和类方法不要交叉放置，不一样存取范围的属性或者方法也尽可能不要交叉放置。(1.42+)

格式：

类定义

{

类的公有属性定义

类的保护属性定义

类的私有属性定义

类的公有方法定义

类的保护方法定义

类的私有方法定义

}

修饰词按照指定顺序书写：[访问权限][static][final] 。(1.42+)

示例：

public static final String str = “abc”;

注释

规则

源程序注释量必须在30％以上。(1.42+)

说明：因为每一个文件的代码注释不必定均可以达到30%，建议以一个系统内部模块做为单位进行检查

包的注释：写入一个名为 package.html 的HTML格式的说明文件放入包所在路径。包的注释内容：简述本包的做用、详细描述本包的内容、产品模块名称和版本、公司版权。(1.42+)

说明：方便JavaDoc收集，方便对包的了解

示例：

com/huawei/iin/websmap/comm/package.html

<html>

<body>

一句话简述。

详细描述。

产品模块名称和版本

公司版权信息

</body>

</html>

示例：

<html>

<body>

为 WEBSMAP 提供通讯类，上层业务使用本包的通讯类与 SMP-B 进行通讯。

详细描述。。。。。。。。

IIN V100R001 WEBSMAP

(C) 版权全部 2000-2001 华为技术有限公司

</body>

</html>

类和接口的注释放在class 或者 interface 关键字以前，import 关键字以后。注释主要是一句话功能简述与功能详细描述。类注释使用“/** */”注释方式(1.42+)

说明：方便JavaDoc收集,没有import可放在package以后。注释可根据须要列出：做者、内容、功能、与其它类的关系等。功能详细描述部分说明该类或者接口的功能、做用、使用方法和注意事项，每次修改后增长做者和更新版本号和日期，@since 表示从那个版本开始就有这个类或者接口，@deprecated 表示不建议使用该类或者接口。

/**

* 〈一句话功能简述〉

* 〈功能详细描述〉

* @author [做者]（必须）

* @see [相关类/方法]（可选）

* @since [产品/模块版本] （必须）

* @deprecated （可选）

示例：

package com.huawei.iin.logwebsmap.comm;

import java.util.*;

/**

* LogManager 类集中控制对日志读写的操做。

* 所有为静态变量和静态方法，对外提供统一接口。分配对应日志类型的读写器，

* 读取或写入符合条件的日志纪录。

* @author 张三，李四，王五

* @see LogIteraotor

* @see BasicLog

* @since CommonLog1.0

public class LogManager

类属性(成员变量)、公有和保护方法注释：写在类属性、公有和保护方法上面，注释方式为“/** */”.(1.42+)

示例：

/**

* 注释内容

private String logType;

/**

* 注释内容

public void write()

公有和保护方法注释内容：列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、异常等。(1.42+)

格式：

/**

* 〈一句话功能简述〉

* 〈功能详细描述〉

* @param [参数1] [参数1说明]

* @param [参数2] [参数2说明]

* @return [返回类型说明]

* @exception/throws [异常类型] [异常说明]

* @see [类、类#方法、类#成员]

* @since [起始版本]

* @deprecated

说明：@since 表示从那个版本开始就有这个方法，若是是最第一版本就存在的方法无需说明；@exception 或throws 列出可能仍出的异常；@deprecated 表示不建议使用该方法。

示例：

/**

* 根据日志类型和时间读取日志。

* 分配对应日志类型的LogReader，指定类型、查询时间段、条件和反复器缓冲数，

* 读取日志记录。查询条件为null或0的表示没有限制，反复器缓冲数为0读不到日志。

* 查询时间为左包含原则，即 [startTime, endTime) 。

* @param logTypeName 日志类型名（在配置文件中定义的）

* @param startTime 查询日志的开始时间

* @param endTime 查询日志的结束时间

* @param logLevel 查询日志的级别

* @param userName 查询该用户的日志

* @param bufferNum 日志反复器缓冲记录数

* @return 结果集，日志反复器

* @since 1.2

public static LogIterator read(String logType, Date startTime, Date endTime, int logLevel, String userName, int bufferNum)

对于方法内部用throw语句抛出的异常，必须在方法的注释中标明，对于所调用的其余方法所抛出的异常，选择主要的在注释中说明。对于非RuntimeException，即throws子句声明会抛出的异常，必须在方法的注释中标明。(1.42+)

说明：异常注释用@exception 或@throws 表示，在JavaDoc中二者等价，但推荐用@exception 标注Runtime异常，@throws 标注非Runtime异常。异常的注释必须说明该异常的含义及什么条件下抛出该异常。

注释应与其描述的代码相近，对代码的注释应放在其上方，并与其上面的代码用空行隔开，注释与所描述内容进行一样的缩排。(1.42+)

说明：可以使程序排版整齐，并方便注释的阅读与理解。

示例：

* 注释

public void example2( )

{

// 注释

CodeBlock One

// 注释

CodeBlock Two

}

* 注释

public void example( )

{

// 注释

CodeBlock One

// 注释

CodeBlock Two

}

对于switch语句下的case语句，必须在每一个case分支结束前加上break语句。(1.42+)

说明：break才能真正表示该switch执行结束，否则可能会进入该case之后的分支。至于语法上合法的场景“一个case后进入下一个case处理”，应该在编码设计上就避免。

修改代码同时修改相应的注释，以保证注释与代码的一致性。再也不有用的注释要删除。(1.42+)

注释的内容要清楚、明了，含义准确，防止注释二义性。(1.42+)

说明：错误的注释不但无益反而有害。

避免在注释中使用缩写，特别是不经常使用缩写。(1.42+)

说明：在使用缩写时或以前，应对缩写进行必要的说明。

对重载父类的方法必须进行@Override声明(5.0+)

说明：可清楚说明此方法是重载父类的方法，保证重载父类的方法时不会由于单词写错而形成错误(写错方法名或者参数个数，类型都会编译没法经过)

示例：

@Override

public void doRequest(SipServletRequest req) throws ServletException,

IOException

建议

避免在一行代码或表达式的中间插入注释。(1.42+)

说明：除非必要，不该在代码或表达中间插入注释，不然容易使代码可理解性变差。

在代码的功能、意图层次上进行注释，提供有用、额外的信息。(1.42+)

说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码之外的信息，帮助读者理解代码，防止不必的重复注释信息。

示例：以下注释意义不大。

// 若是 receiveFlag 为真

if (receiveFlag)

而以下的注释则给出了额外有用的信息。

// 若是从连结收到消息

if (receiveFlag)

对关键变量的定义和分支语句（条件分支、循环语句等）必须编写注释。(1.42+)

说明：这些语句每每是程序实现某一特定功能的关键，对于维护人员来讲，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。

注释应考虑程序易读及外观排版的因素，使用的语言如果中、英兼有的，建议多使用中文，除非能用很是流利准确的英文表达。中文注释中需使用中文标点。方法和类描述的第一句话尽可能使用简洁明了的话归纳一下功能，而后加以句号。接下来的部分能够详细描述。(1.42+)

说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文。JavaDoc工具收集简介的时候使用选取第一句话。

方法内的单行注释使用 //。(1.42+)

说明：调试程序的时候能够方便的使用 /* 。。。*/ 注释掉一长段程序。

一些复杂的代码须要说明。(1.42+)

示例：这里主要是对闰年算法的说明。

//1. 若是能被4整除，是闰年；

//2. 若是能被100整除，不是闰年；

//3. 若是能被400整除，是闰年。

使用Html标签使JavaDoc生成更加美观。(1.42+)

示例：

/**

* Returns a hash code for this string. The hash code for a

* <code>String</code> object is computed as

* <blockquote><pre>

* s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1]

* </pre></blockquote>

* using <code>int</code> arithmetic, where <code>s[i]</code> is the

* ith character of the string, <code>n</code> is the length * of

* the string, and <code>^</code> indicates exponentiation.

* (The hash value of the empty string is zero.)

* @return a hash code value for this object.

public int hashCode()

生成后的JavaDoc

命名

规则

类名和接口使用类意义完整的英文描述，每一个英文单词的首字母使用大写、其他字母使用小写的大小写混合法。(1.42+)

示例：OrderInformation, CustomerList, LogManager, LogConfig, SmpTransaction

方法名使用类意义完整的英文描述：第一个单词的字母使用小写、剩余单词首字母大写其他字母小写的大小写混合法。(1.42+)

示例：

private void calculateRate();

public void addNewOrder();

方法中，存取属性的方法采用setter 和 getter方法，动做方法采用动词和动宾结构。(1.42+)

格式：

get + 非布尔属性名()

is + 布尔属性名()

set + 属性名()

动词()

动词 + 宾语()

示例：

public String getType();

public boolean isFinished();

public void setVisible(boolean);

public void show();

public void addKeyListener(Listener);

属性名使用意义完整的英文描述，第一个单词的字母使用小写，剩余单词首字母大写其他字母小写的大小写混合法。属性名不能与方法名相同。(1.42+)

示例：

private customerName;

private orderNumber;

private smpSession;

常量名使用全大写的英文描述，英文单词之间用下划线分隔开，而且使用 static final修饰。(1.42+)

示例：

public static final int MAX_VALUE = 1000;

public static final String DEFAULT_START_DATE = "2001-12-08";

建议

包名采用域后缀倒置的加上自定义的包名，采用小写字母，都应该以com.huawei开头(不包括一些特殊缘由)。在部门内部应该规划好包名的范围，防止产生冲突。部门内部产品使用部门的名称加上模块名称。产品线的产品使用产品的名称加上模块的名称。(1.42+)

说明：除特殊缘由包结构都必须以com.huawei开头，若是由于OEM合做等关系，能够不作要求。

格式：

com.huawei.产品名.模块名称

示例：

融合WEBSMAP包名 com.huawei.iin.websmap

经过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。(1.42+)

说明：清晰准确的函数、变量等的命名，可增长代码可读性，并减小没必要要的注释。

经常使用组件类的命名以组件名加上组件类型名结尾。(1.42+)

示例：

Application 类型的，命名以App 结尾——MainApp

Frame 类型的，命名以Frame 结尾——TopoFrame

Panel 类型的，建议命名以Panel 结尾——CreateCircuitPanel

Bean 类型的，建议命名以Bean 结尾——DataAccessBean

EJB 类型的，建议命名以EJB 结尾——DBProxyEJB

Applet 类型的，建议命名以Applet 结尾——PictureShowApplet

若是函数名超过15 个字母，可采用以去掉元音字母的方法或者以行业内约定俗成的缩写方式缩写函数名。(1.42+)

示例：

getCustomerInformation() 改成 getCustomerInfo()

准确地肯定成员函数的存取控制符号:只是该类内部调用的函数使用 private 属性，继承类可使用的使用protected属性，同包类能够调用的使用默认属性(不加属性控制符号)，对外公开的函数使用public属性(1.42+)

示例：

protected void getUserName()

{

。。。。。。

}

private void calculateRate()

{

。。。。。。

}

含有集合意义的属性命名，尽可能包含其复数的意义。(1.42+)

示例：

customers, orderItems

编码

规则

数据库操做、IO操做等须要使用结束close()的对象必须在try -catch-finally 的finally中close()，若是有多个IO对象须要close()，须要分别对每一个对象的close()方法进行try-catch,防止一个IO对象关闭失败其余IO对象都未关闭。(1.42+)

示例：

try

{

// ... ...

}

catch(IOException ioe)

{

//... ...

}

finally

{

try

{

out.close();

}

catch (IOException ioe)

{

//... ...

}

try

{

in.close();

}

catch (IOException ioe)

{

//... ...

}

系统非正常运行产生的异常捕获后，若是不对该异常进行处理，则应该记录日志。 (1.42+)

说明：此规则指一般的系统非正常运行产生的异常，不包括一些基于异常的设计。如有特殊缘由必须用注释加以说明。

示例：

try

{

//.... ...

}

catch (IOException ioe)

{

logger.error(ioe);

}

本身抛出的异常必需要填写详细的描述信息。(1.42+)

说明：便于问题定位。

示例：

throw new IOException("Writing data error! Data: " + data.toString());

运行时异常使用RuntimeException的子类来表示，不用在可能抛出异常的方法声明上加throws子句。非运行期异常是从Exception继承而来的，必须在方法声明上加throws子句。(1.42+)

说明：

非运行期异常是由外界运行环境决定异常抛出条件的异常，例如文件操做，可能授权限、磁盘空间大小的影响而失败，这种异常是程序自己没法避免的，须要调用者明确考虑该异常出现时该如何处理方法，所以非运行期异常必须有throws子句标出，不标出或者调用者不捕获该类型异常都会致使编译失败，从而防止程序员自己疏忽。

运行期异常是程序在运行过程当中自己考虑不周致使的异常，例如传入错误的参数等。抛出运行期异常的目的是防止异常扩散，致使定位困难。所以在作异常体系设计时要根据错误的性质合理选择自定义异常的继承关系。

还有一种异常是Error 继承而来的，这种异常由虚拟机本身维护，表示发生了致命错误，程序没法继续运行例如内存不足。咱们本身的程序不该该捕获这种异常，而且也不该该建立该种类型的异常。

在程序中使用异常处理仍是使用错误返回码处理，根据是否有利于程序结构来肯定，而且异常和错误码不该该混合使用，推荐使用异常。(1.42+)

说明：

一个系统或者模块应该统一规划异常类型和返回码的含义。

可是不能用异常来作通常流程处理的方式，不要过多地使用异常，异常的处理效率比条件分支低，并且异常的跳转流程难以预测。

注意：Java 5.0 程序内部的错误码可使用枚举来表示。

注意运算符的优先级，并用括号明确表达式的操做顺序，避免使用默认优先级。(1.42+)

说明：防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而致使程序出错。

示例：

下列语句中的表达式

word = (high << 8) | low (1)

if ((a | b) && (a & c)) (2)

if ((a | b) < (c & d)) (3)

若是书写为

high << 8 | low

a | b && a & c

a | b < c & d

（1）（2）虽然不会出错，但语句不易理解；（3）形成了判断条件出错。

避免使用不易理解的数字，用有意义的标识来替代。涉及物理状态或者含有物理意义的常量，不该直接使用数字，必须用有意义的静态变量或者枚举来代替。使用异常来表示方法执行错误，而不是使用C++的错误返回码方式。(1.42+)

示例：以下的程序可读性差。

if (state == 0)

{

state = 1;

... // program code

}

应改成以下形式：

private final static int TRUNK_IDLE = 0;

private final static int TRUNK_BUSY = 1;

private final static int TRUNK_UNKNOWN = -1;

if (state == TRUNK_IDLE)

{

state = TRUNK_BUSY;

... // program code

}

注意：Java 5.0 下建议使用枚举来表示。

异常：

public void function()

{

...

throw new RuntimeException(“。。。”);

}

数组声明的时候使用 int[] index ，而不要使用 int index[] 。(1.42+)

说明：使用int index[] 格式使程序的可读性较差，int [] index 表示声明了一个int数组(int [])叫作index

示例：

以下程序可读性差：

public int getIndex()[]

{

....

}

以下程序可读性好：

public int[] getIndex()

{

....

}

不要使用 System.out 与 System.err 进行控制台打印，应该使用工具类(如：日志工具)进行统一记录或者打印。(1.42+)

说明：代码发布的时候能够统一关闭控制台打印，代码调试的时候又能够打开控制台打印，方便调试。

用调测开关来切换软件的DEBUG版和正式版，而不要同时存在正式版本和DEBUG版本的不一样源文件，以减小维护的难度。 (1.42+)

集合必须指定模板类型(5.0+)

说明：方便程序阅读，除去强制转换代码

示例：

Map<String,MyObject> map = new HashMap<String,MyObject>();

一个文件不要定义两个类(并不是指内部类)。(1.42+)

说明：方便程序的阅读与代码的维护

全部的数据类必须覆写toString()、hashCode()、equals() 方法，toString()方法返回该类有意义的内容。(1.42+)

说明：方便数据类的比较，父类若是实现了比较合理的toString() ，子类能够继承没必要再重写。

hashCode与equals可使用eclipse自动生成。

示例：

public TopoNode

{

private String nodeName;

public String toString()

{

return "NodeName : " + nodeName;

}

判断语句不要使用”* == true”来判断为真

说明：方便阅读，减小没有必要的计算

如下错误：

if (ok == true)

{

……

}

如下正确：

if (ok)

{

……

}

不要写没有必要的向上强制转型。(1.42+)

说明：不必写的向上强制转型会浪费性能，增长代码阅读难度

示例：

如下错误：

FileInputStream fis = new FileInputStream(f);

InputStream is = (InputStream)fis;

建议

记录异常不要保存exception.getMessage()，而要记录exception.toString()，通常可经过日志工具记录完整的异常堆栈信息。(1.42+)

说明：NullPointException抛出时经常描述为空，这样每每看不出是出了什么错。

示例：

try

{

...

}

catch (FileNotFoundException e)

{

logger.error(e);

}

一个方法不该抛出太多类型的异常。(1.42+)

说明：若是程序中须要分类处理，则将异常根据分类组织成继承关系。若是确实有不少异常类型首先考虑用异常描述来区别，throws/exception子句标明的异常最好不要超过三个。

异常捕获尽可能不要直接 catch (Exception ex)，应该把异常细分处理。(1.42+)

说明：能够设计更合理异常处理分支

若是多段代码重复作同一件事情，那么在方法的划分上可能存在问题。(1.42+)

说明：若此段代码各语句之间有实质性关联而且是完成同一件功能的，那么可考虑把此段代码构形成一个新的方法。

集合中的数据若是不使用了应该及时释放，尤为是可重复使用的集合。(1.42+)

说明：因为集合保存了对象的引用，虚拟机的垃圾收集器就不会回收。

源程序中关系较为紧密的代码应尽量相邻。(1.42+)

说明：便于程序阅读和查找。

示例：矩形的长与宽关系较密切，放在一块儿。

rect.length = 10;

rect.width = 5;

不要使用难懂的技巧性很高的语句，除非颇有必要时。(1.42+)

说明：高技巧语句不等于高效率的程序，实际上程序的效率关键在于设计与算法。

明确方法功能，精确（而不是近似）地实现方法设计。一个函数仅完成一件功能，即便简单功能也编写方法实现。(1.42+)

说明：虽然为仅用一两行就可完成的功能去编方法好象没有必要，但用方法可以使功能明确化，增长程序可读性，亦可方便维护、测试。

应明确规定对接口方法参数的合法性检查应由方法的调用者负责仍是由接口方法自己负责，缺省是由方法调用者负责。(1.42+)

说明：对于模块间接口方法的参数的合法性检查这一问题，每每有两个极端现象，即：要么是调用者和被调用者对参数均不做合法性检查，结果就遗漏了合法性检查这一必要的处理过程，形成问题隐患；要么就是调用者和被调用者均对参数进行合法性检查，这种状况虽不会形成问题，但产生了冗余代码，下降了效率。

尽可能使用Java 5.0新循环写法。(5.0+)

说明：代码更加简洁

示例：

ArrayList<String> list = new ArrayList<String>();

list.add...

for(String str:list)

{

System.out.println(str);

}

使用Java 5.0枚举来替代之前用数字与字符串的同等目的的操做。(5.0+)

说明：Java 5.0之前没有枚举，你们都用数字或者字符串作枚举一样功能的事情

示例：

public enum EnumDemo

{

ERROR,INFO,DEBUG

}

In other function：

EnumDemo t = EnumDemo.DEBUG;

if (t == EnumDemo.ERROR)

{

。。。。。。

}

interface 中定义的常量不要写public、static、final的修饰词，方法不要写public修饰词。(1.42+)

说明：更加简洁

示例：

public interface InterfaceT

{

String TT = "abcl";

void doStart();

}

新起一个线程，都要使用Thread.setName(“…”)设置线程名。

说明：性能测试时可对线程状态进行监控，异常时也能够知道异常发生在哪一个线程中

性能与可靠性

规则

对Debug，Info级别日志输出前必须对当前的调试等级先进行判断。(1.42+)

说明：日志通常都会有很多字符串的处理，若是不是Debug级别就没有必要进行处理

示例：

if (logger.debugEnable())

{

logger.debug(“request : ” + request.getMethod());

}

数组复制使用System.arraycopy(*) 。(1.42+)

说明：更好的性能

不要使用循环将集合转为数组，可使用集合的toArray()方法。(1.42+)

说明：更好的性能，代码更加简洁

示例：

ArrayList list = new ArrayList();

list.add....

String [] array = new String[list.size()];

list.toArray(array);

大量字符串的相加等于处理应该使用StringBuffer。(1.42+)

说明：大量的String相加等于处理性能消耗较多。“大量”通常指5次“+=”以上或者在循环中进行字符串+=操做。

示例：

不推荐：

String str = “”;

str += ”a”;

str += ”b”;