Java语言编程规范基础篇.docx
《Java语言编程规范基础篇.docx》由会员分享，可在线阅读，更多相关《Java语言编程规范基础篇.docx（28页珍藏版）》请在冰豆网上搜索。
Java语言编程规范基础篇
Java语言编程规范_基础篇
排版
规则1.1 程序块要采用缩进风格编写，缩进的空格数为4个，不允许使用TAB缩进。
说明：
缩进使程序更易阅读，使用空格缩进可以适应不同操作系统与不同开发工具。
规则1.2 分界符（如大括号‘{’和‘}’）应各独占一行，同时与引用它们的语句左对齐。
在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序或者static、,synchronized等语句块中都要采用如上的缩进方式。
示例:
if（a>b）
{
doStart（）;
}
规则1.3 较长的语句、表达式或参数（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。
示例：
if（logger.isDebugEnabled（））
{
logger.debug（"Sessiondestroyed,call-id"
+event.getSession（）.getCallId（））;
}
规则1.4 不允许把多个短语句写在一行中，即一行只写一条语句
说明：
阅读代码更加清晰
示例：
如下例子不符合规范。
Objecto=newObject（）;Objectb=null;
规则1.5if,for,do,while,case,switch,default等语句自占一行，且if,for,do,while,switch等语句的执行语句无论多少都要加括号{},case的执行语句中如果定义变量必须加括号{}。
说明：
读代码更加清晰，减少错误产生
示例：
if（a>b）
{
doStart（）;
}
casex:
{
inti=9
}
规则1.6相对独立的程序块之间、变量说明之后必须加空行。
说明:
阅读代码更加清晰
示例：
if（a>b）
{
doStart（）;
}
//此处是空行
return;
规则1.7 在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如.），后不应加空格。
说明：
阅读代码更加清晰
示例：
if（a==b）
{
ObjectA.doStart（）;
}
a*=2;
建议1.8 类属性和类方法不要交叉放置，不同存取范围的属性或者方法也尽量不要交叉放置。
格式：
类定义
{
类的公有属性定义
类的保护属性定义
类的私有属性定义
类的公有方法定义
类的保护方法定义
类的私有方法定义
}
建议1.9修饰词按照指定顺序书写：
[访问权限][static][final]。
示例：
publicstaticfinalStringstr=“abc”;
注释
规则2.1 源程序注释量必须在30％以上。
说明：
由于每个文件的代码注释不一定都可以达到30%，建议以一个系统内部模块作为单位进行检查
规则2.2 包的注释：
写入一个名为package.html的HTML格式的说明文件放入包所在路径。
包的注释内容：
简述本包的作用、详细描述本包的内容、产品模块名称和版本、公司版权。
说明：
方便JavaDoc收集，方便对包的了解
示例：
com/cetc/iin/websmap/comm/package.html
一句话简述。
详细描述。
产品模块名称和版本
公司版权信息
示例：
为WEBSMAP提供通信类，上层业务使用本包的通信类与SMP-B进行通信。
详细描述。
。
。
。
。
。
。
。
IINV100R001WEBSMAP
（C）版权所有2000-2001
规则2.3类和接口的注释放在class或者interface关键字之前，import关键字之后。
注释主要是一句话功能简述与功能详细描述。
类注释使用“/** */”注释方式
说明：
方便JavaDoc收集,没有import可放在package之后。
注释可根据需要列出：
作者、内容、功能、与其它类的关系等。
功能详细描述部分说明该类或者接口的功能、作用、使用方法和注意事项，每次修改后增加作者和更新版本号和日期，@since表示从那个版本开始就有这个类或者接口，@deprecated表示不建议使用该类或者接口。
/**
*〈一句话功能简述〉
*〈功能详细描述〉
*@author [作者]（必须）
*@see [相关类/方法]（可选）
*@since [产品/模块版本]（必须）
*@deprecated （可选）
*/
示例：
packagem;
importjava.util.*;
/**
*LogManager类集中控制对日志读写的操作。
*全部为静态变量和静态方法，对外提供统一接口。
分配对应日志类型的读写器，
*读取或写入符合条件的日志纪录。
*@author 张三，李四，王五
*@see LogIteraotor
*@see BasicLog
*@since CommonLog1.0
*/
publicclassLogManager
规则2.4类属性（成员变量）、公有和保护方法注释：
写在类属性、公有和保护方法上面，注释方式为“/** */”.
示例：
/**
*注释内容
*/
privateStringlogType;
/**
*注释内容
*/
publicvoidwrite（）
规则2.5公有和保护方法注释内容：
列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、异常等。
格式：
/**
*〈一句话功能简述〉
*〈功能详细描述〉
*@param[参数1] [参数1说明]
*@param[参数2] [参数2说明]
*@return [返回类型说明]
*@exception/throws[异常类型][异常说明]
*@see [类、类#方法、类#成员]
*@since[起始版本]
*@deprecated
*/
说明：
@since表示从那个版本开始就有这个方法，如果是最初版本就存在的方法无需说明；@exception或throws列出可能仍出的异常；@deprecated表示不建议使用该方法。
示例：
/**
*根据日志类型和时间读取日志。
*分配对应日志类型的LogReader，指定类型、查询时间段、条件和反复器缓冲数，
*读取日志记录。
查询条件为null或0的表示没有限制，反复器缓冲数为0读不到日志。
*查询时间为左包含原则，即[startTime,endTime）。
*@paramlogTypeName 日志类型名（在配置文件中定义的）
*@paramstartTime 查询日志的开始时间
*@paramendTime 查询日志的结束时间
*@paramlogLevel 查询日志的级别
*@paramuserName 查询该用户的日志
*@parambufferNum 日志反复器缓冲记录数
*@return 结果集，日志反复器
*@since 1.2
*/
publicstaticLogIteratorread（StringlogType,DatestartTime, DateendTime,intlogLevel,StringuserName,intbufferNum）
规则2.6对于方法内部用throw语句抛出的异常，必须在方法的注释中标明，对于所调用的其他方法所抛出的异常，选择主要的在注释中说明。
对于非RuntimeException，即throws子句声明会抛出的异常，必须在方法的注释中标明。
说明：
异常注释用@exception或@throws表示，在JavaDoc中两者等价，但推荐用@exception标注Runtime异常，@throws标注非Runtime异常。
异常的注释必须说明该异常的含义及什么条件下抛出该异常。
规则2.7注释应与其描述的代码相近，对代码的注释应放在其上方，并与其上面的代码用空行隔开，注释与所描述内容进行同样的缩排。
说明：
可使程序排版整齐，并方便注释的阅读与理解。
示例：
/*
*注释
*/
publicvoidexample2（）
{
//注释
CodeBlockOne
//注释
CodeBlockTwo
}
/*
*注释
*/
publicvoidexample（）
{
//注释
CodeBlockOne
//注释
CodeBlockTwo
}
规则2.8 对于switch语句下的case语句，必须在每个case分支结束前加上break语句。
说明：
break才能真正表示该switch执行结束，不然可能会进入该case以后的分支。
至于语法上合法的场景“一个case后进入下一个case处理”，应该在编码设计上就避免。
规则2.9 修改代码同时修改相应的注释，以保证注释与代码的一致性。
不再有用的注释要删除。
规则2.10 注释的内容要清楚、明了，含义准确，防止注释二义性。
说明：
错误的注释不但无益反而有害。
规则2.11避免在注释中使用缩写，特别是不常用缩写。
说明：
在使用缩写时或之前，应对缩写进行必要的说明。
规则2.12对重载父类的方法必须进行@Override声明
说明：
可清楚说明此方法是重载父类的方法，保证重载父类的方法时不会因为单词写错而造成错误（写错方法名或者参数个数，类型都会编译无法通过）
示例：
@Override
publicvoiddoRequest（SipServletRequestreq）throwsServletException,
IOException
建议2.13 避免在一行代码或表达式的中间插入注释。
说明：
除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。
建议2.14 在代码的功能、意图层次上进行注释，提供有用、额外的信息。
说明：
注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。
示例：
如下注释意义不大。
//如果receiveFlag为真
if（receiveFlag）
而如下的注释则给出了额外有用的信息。
//如果从连结收到消息
if（receiveFlag）
建议2.15 对关键变量的定义和分支语句（条件分支、循环语句等）必须编写注释。
说明：
这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。
建议2.16注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。
中文注释中需使用中文标点。
方法和类描述的第一句话尽量使用简洁明了的话概括一下功能，然后加以句号。
接下来的部分可以详细描述。
说明：
注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文。
JavaDoc工具收集简介的时候使用选取第一句话。
建议2.17方法内的单行注释使用//。
说明：
调试程序的时候可以方便的使用/*。
。
。
*/注释掉一长段程序。
建议2.18 一些复杂的代码需要说明。
示例：
这里主要是对闰年算法的说明。
//1.如果能被4整除，是闰年；
//2.如果能被100整除，不是闰年；
//3.如果能被400整除，是闰年。
命名
规则3.1类名和接口使用类意义完整的英文描述，每个英文单词的首字母使用大写、其余字母使用小写的大小写混合法。
示例：
OrderInformation,CustomerList,LogManager,LogConfig,SmpTransaction
规则3.2方法名使用类意义完整的英文描述：
第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。
示例：
privatevoidcalculateRate（）;
publicvoidaddNewOrder（）;
规则3.3方法中，存取属性的方法采用setter和getter方法，动作方法采用动词和动宾结构。
格式：
get+非布尔属性名（）
is+布尔属性名（）
set+属性名（）
动词（）
动词+宾语（）
示例：
publicStringgetType（）;
publicbooleanisFinished（）;
publicvoidsetVisible（boolean）;
publicvoidshow（）;
publicvoidaddKeyListener（Listener）;
规则3.4属性名使用意义完整的英文描述，第一个单词的字母使用小写，剩余单词首字母大写其余字母小写的大小写混合法。
属性名不能与方法名相同。
示例：
privatecustomerName;
privateorderNumber;
privatesmpSession;
规则3.5常量名使用全大写的英文描述，英文单词之间用下划线分隔开，并且使用staticfinal修饰。
示例：
publicstaticfinalintMAX_VALUE=1000;
publicstaticfinalStringDEFAULT_START_DATE="2001-12-08";
建议3.6包名采用域后缀倒置的加上自定义的包名，采用小写字母，都应该以com.cetc开头（不包括一些特殊原因）。
在部门内部应该规划好包名的范围，防止产生冲突。
部门内部产品使用部门的名称加上模块名称。
产品线的产品使用产品的名称加上模块的名称。
说明：
除特殊原因包结构都必须以com.cetc开头，如果因为OEM合作等关系，可以不做要求。
格式：
com.cetc.产品名.模块名称
示例：
融合WEBSMAP包名 com.cetc.iin.websmap
建议3.7通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。
说明：
清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。
建议3.8常用组件类的命名以组件名加上组件类型名结尾。
示例：
Application类型的，命名以App结尾——MainApp
Frame类型的，命名以Frame结尾——TopoFrame
Panel类型的，建议命名以Panel结尾——CreateCircuitPanel
Bean类型的，建议命名以Bean结尾——DataAccessBean
EJB类型的，建议命名以EJB结尾——DBProxyEJB
Applet类型的，建议命名以Applet结尾——PictureShowApplet
建议3.9如果函数名超过15个字母，可采用以去掉元音字母的方法或者以行业内约定俗成的缩写方式缩写函数名。
示例：
getCustomerInformation（） 改为 getCustomerInfo（）
建议3.10 准确地确定成员函数的存取控制符号:
只是该类内部调用的函数使用private属性，继承类可以使用的使用protected属性，同包类可以调用的使用默认属性（不加属性控制符号），对外公开的函数使用public属性
示例：
protectedvoidgetUserName（）
{
……
}
privatevoidcalculateRate（）
{
……
}
建议3.11含有集合意义的属性命名，尽量包含其复数的意义。
示例：
customers, orderItems
编码
规则4.1 数据库操作、IO操作等需要使用结束close（）的对象必须在try-catch-finally的finally中close（），如果有多个IO对象需要close（），需要分别对每个对象的close（）方法进行try-catch,防止一个IO对象关闭失败其他IO对象都未关闭。
示例：
try
{
//......
}
catch（IOExceptionioe）
{
//......
}
finally
{
try
{
out.close（）;
}
catch（IOExceptionioe）
{
//......
}
try
{
in.close（）;
}
catch（IOExceptionioe）
{
//......
}
}
规则4.2系统非正常运行产生的异常捕获后，如果不对该异常进行处理，则应该记录日志。
说明：
此规则指通常的系统非正常运行产生的异常，不包括一些基于异常的设计。
若有特殊原因必须用注释加以说明。
示例：
try
{
//.......
}
catch（IOExceptionioe）
{
logger.error（ioe）;
}
规则4.3自己抛出的异常必须要填写详细的描述信息。
说明：
便于问题定位。
示例：
thrownew IOException（"Writingdataerror!
Data:
"+data.toString（））;
规则4.4 运行时异常使用RuntimeException的子类来表示，不用在可能抛出异常的方法声明上加throws子句。
非运行期异常是从Exception继承而来的，必须在方法声明上加throws子句。
说明：
非运行期异常是由外界运行环境决定异常抛出条件的异常，例如文件操作，可能受权限、磁盘空间大小的影响而失败，这种异常是程序本身无法避免的，需要调用者明确考虑该异常出现时该如何处理方法，因此非运行期异常必须有throws子句标出，不标出或者调用者不捕获该类型异常都会导致编译失败，从而防止程序员本身疏忽。
运行期异常是程序在运行过程中本身考虑不周导致的异常，例如传入错误的参数等。
抛出运行期异常的目的是防止异常扩散，导致定位困难。
因此在做异常体系设计时要根据错误的性质合理选择自定义异常的继承关系。
还有一种异常是Error继承而来的，这种异常由虚拟机自己维护，表示发生了致命错误，程序无法继续运行例如内存不足。
我们自己的程序不应该捕获这种异常，并且也不应该创建该种类型的异常。
规则4.5 在程序中使用异常处理还是使用错误返回码处理，根据是否有利于程序结构来确定，并且异常和错误码不应该混合使用，推荐使用异常。
说明：
一个系统或者模块应该统一规划异常类型和返回码的含义。
但是不能用异常来做一般流程处理的方式，不要过多地使用异常，异常的处理效率比条件分支低，而且异常的跳转流程难以预测。
注意：
Java 5.0程序内部的错误码可以使用枚举来表示。
规则4.6 注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。
说明：
防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。
示例：
下列语句中的表达式
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（1）
（2）虽然不会出错，但语句不易理解；（3）造成了判断条件出错。
规则4.7避免使用不易理解的数字，用有意义的标识来替代。
涉及物理状态或者含有物理意义的常量，不应直接使用数字，必须用有意义的静态变量或者枚举来代替。
使用异常来表示方法执行错误，而不是使用C++的错误返回码方式。
示例：
如下的程序可读性差。
if（state==0）
{
state=1;
... //programcode
}
应改为如下形式：
privatefinalstaticintTRUNK_IDLE=0;
privatefinalstaticintTRUNK_BUSY=1;
privatefinalstaticintTRUNK_UNKNOWN=-1;
if（state==TRUNK_IDLE）
{
state=TRUNK_BUSY;
... //programcode
}
注意：
Java5.0下建议使用枚举来表示。
异常：
publicvoidfunction（）
{
...
thrownewRuntimeException（“…”）;
}
规则4.8 数组声明的时候使用int[]index，而不要使用intindex[]。
说明：
使用intindex[]格式使程序的可读性较差，int[]index表示声明了一个int数组（int[]）叫做index
示例：
如下程序可读性差：
publicintgetIndex（）[]
{
....
}
如下程序可读性好：
publicint[]getIndex（）
{
....
}
规则4.9不要使用System.out与System.err进行控制台打印，应该使用工具类（如：
日志工具）进行统一记录或者打印。
说明：
代码发布的时候可以统一关闭控制台打印，代码调试的时候又可以打开控制台打印，方便调试。
规则4.10用调测开关来切换软件的DEBUG版和正式版，而不要同时存在正式版本和DEBUG版本的不同源文件，以减少维护的难度。
规则4.
升级会员 