华为Java语言编码规范.docx
- 文档编号:10362090
- 上传时间:2023-02-10
- 格式:DOCX
- 页数:28
- 大小:29.70KB
华为Java语言编码规范.docx
《华为Java语言编码规范.docx》由会员分享,可在线阅读,更多相关《华为Java语言编码规范.docx(28页珍藏版)》请在冰豆网上搜索。
华为Java语言编码规范
Documentnumber文档编号
Confidentialitylevel密级
内部公开
Documentversion文档版本
Total29pages共29页
Java语言编码规范
Preparedby
拟制
Date
日期
yyyy-mm-dd
Reviewedby
评审人
Date
日期
yyyy-mm-dd
Approvedby
批准
Date
日期
yyyy-mm-dd
RevisionRecord修订记录
Date
日期
RevisionVersion
修订版本
SecNo.
修改章节
ChangeDescription
修改描述
Author
作者
yyyy-mm-dd
TableofContents目录
1.范围4
2.规范性引用文件4
3.术语和定义4
4.排版规范5
.规则5
.建议7
5.注释规范8
.规则8
.建议13
6.命名规范16
.规则16
.建议17
7.编码规范19
.规则19
.建议23
8.JTEST规范25
.规则25
.建议26
1.范围
本规范规定了使用Java语言编程时排版、注释、命名、编码和JTEST的规则和建议。
本规范适用于使用Java语言编程的产品和项目。
2.规范性引用文件
下列文件中的条款通过本规范的引用而成为本规范的条款。
凡是注日期的引用文件,其随后所有的修改单(不包括勘误的内容)或修订版均不适用于本规范,然而,鼓励根据本规范达成协议的各方研究是否可使用这些文件的最新版本。
凡是不注日期的引用文件,其最新版本适用于本规范。
序号
编号
名称
1
公司-
《Java语言编程规范》
3.术语和定义
规则:
编程时强制必须遵守的原则。
建议:
编程时必须加以考虑的原则。
格式:
对此规范格式的说明。
说明:
对此规范或建议进行必要的解释。
示例:
对此规范或建议从正、反两个方面给出例子。
4.排版规范
4.1.规则
4.1.1.*程序块要采用缩进风格编写,缩进的空格数为4个。
说明:
对于由开发工具自动生成的代码可以有不一致。
4.1.2.*分界符(如大括号‘{’和‘}’)应各独占一行并且位于同一列,同时与引用它们的语句左对齐。
在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
示例:
如下例子不符合规范。
for(...){
....)
{
.....)
{
....)
{
....ength()<())
{
4.1.3....,后不应加空格。
说明:
采用这种松散方式编写代码的目的是使代码更加清晰。
由于留空格所产生的清晰性是相对的,所以,在已经非常清晰的语句中没有必要再留空格,如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格,多重括号间不必加空格,因为在Java语言中括号已经是最清晰的标志了。
在长语句中,如果需要加的空格非常多,那么应该保持整体清晰,而在局部不加空格。
给操作符留空格时不要连续留两个以上空格。
示例:
(1)逗号、分号只在后面加空格。
inta,b,c;
(2)比较操作符,赋值操作符"="、"+=",算术操作符"+"、"%",逻辑操作符"&&"、"&",位域操作符"<<"、"^"等双目操作符的前后加空格。
if(current_time>=MAX_TIME_VALUE)
a=b+c;
a*=2;
a=b^2;
(3)"!
"、"~"、"++"、"--"、"&"(地址运算符)等单目操作符前后不加空格。
(4)flag=!
isEmpty;前后不加空格。
=pid;前后不加空格
(5)if、for、while、switch等与后面的括号间应加空格,使if等关键字更为突出、明显。
if(a>=b&&c>d)
4.2.建议
类属性和类方法不要交叉放置,不同存取范围的属性或者方法也尽量不要交叉放置。
格式:
类定义
{
类的公有属性定义
类的保护属性定义
类的私有属性定义
类的公有方法定义
类的保护方法定义
类的私有方法定义
}
5.注释规范
5.1.规则
5.1.1.一般情况下,源程序有效注释量必须在30%以上。
说明:
注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。
可以用注释统计工具来统计。
5.1.2.包的注释:
包的注释写入一名为的HTML格式说明文件放入当前路径。
说明:
方便JavaDoc收集
示例:
com/huawei/msg/relay/comm/
5.1.3.包的注释内容:
简述本包的作用、详细描述本包的内容、产品模块名称和版本、公司版权。
说明:
在详细描述中应该说明这个包的作用以及在整个项目中的位置。
格式:
一句话简述。
详细描述。
产品模块名称和版本
公司版权信息
示例:
为Relay提供通信类,上层业务使用本包的通信类与SP进行通信。
详细描述。
。
。
。
。
。
。
。
MMSCV100R002Relay
(C)版权所有2002-2007文思创新技术有限公司
5.1.4.文件注释:
文件注释写入文件头部,包名之前的位置。
说明:
注意以/*开始避免被JavaDoc收集
示例:
/*
*注释内容
*/
5.1.5.package文件注释内容:
版权说明、描述信息、生成日期、修改历史。
说明:
文件名可选。
格式:
/*
*文件名:
[文件名]
*版权:
〈版权〉
*描述:
〈描述〉
*修改人:
〈修改人〉
*修改时间:
YYYY-MM-DD
*修改单号:
〈修改单号〉
*修改内容:
〈修改内容〉
*/
说明:
每次修改后在文件头部写明修改信息,CheckIn的时候可以直接把蓝色字体信息粘贴到VSS的注释上。
在代码受控之前可以免去。
示例:
/*
*文件名:
*版权:
Copyright2002-2007HuaweiTech.Co.Ltd.AllRightsReserved.
*描述:
MMSCV100R002Relay通用日志系统
*修改人:
张三
*修改时间:
2001-02-16
*修改内容:
新增
*修改人:
李四
*修改时间:
2001-02-26
*修改单号:
WSS368
*修改内容:
。
。
。
。
。
。
*修改人:
王五
*修改时间:
2001-03-25
*修改单号:
WSS498
*修改内容:
。
。
。
。
。
。
*/
5.1.6.类和接口的注释:
该注释放在package关键字之后,class或者interface关键字之前。
说明:
方便JavaDoc收集。
示例:
package*注释内容
*/
publicclassCommManager
5.1.7.类和接口的注释内容:
类的注释主要是一句话功能简述、功能详细描述。
说明:
可根据需要列出:
版本号、生成日期、作者、内容、功能、与其它类的关系等。
如果一个类存在Bug,请如实说明这些Bug。
格式:
/**
*〈一句话功能简述〉
*〈功能详细描述〉
*@author[作者]
*@version[版本号,YYYY-MM-DD]
*@see[相关类/方法]
*@since[产品/模块版本]
*@deprecated
*/
说明:
描述部分说明该类或者接口的功能、作用、使用方法和注意事项,每次修改后增加作者和更新版本号和日期,@since表示从那个版本开始就有这个类或者接口,@deprecated表示不建议使用该类或者接口。
示例:
/**
*LogManager类集中控制对日志读写的操作。
*全部为静态变量和静态方法,对外提供统一接口。
分配对应日志类型的读写器,
*读取或写入符合条件的日志纪录。
*@author张三,李四,王五
*@version,2001-03-25
*@seeLogIteraotor
*@seeBasicLog
*@since
*/
5.1.8.类属性、公有和保护方法注释:
写在类属性、公有和保护方法上面。
示例:
/**
*注释内容
*/
privateStringlogType;
/**
*注释内容
*/
publicvoidwrite()
5.1.9.成员变量注释内容:
成员变量的意义、目的、功能,可能被用到的地方。
5.1.10.公有和保护方法注释内容:
列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。
格式:
/**
*〈一句话功能简述〉
*〈功能详细描述〉
*@param[参数1][参数1说明]
*@param[参数2][参数2说明]
*@return[返回类型说明]
*@exception/throws[违例类型][违例说明]
*@see[类、类#方法、类#成员]
*@deprecated
*/
说明:
@since表示从那个版本开始就有这个方法;@exception或throws列出可能仍出的异常;@deprecated表示不建议使用该方法。
示例:
/**
*根据日志类型和时间读取日志。
*分配对应日志类型的LogReader,指定类型、查询时间段、条件和反复器缓冲数,
*读取日志记录。
查询条件为null或0表示无限制,反复器缓冲数为0读不到日志。
*查询时间为左包含原则,即[startTime,endTime)。
*@paramlogTypeName日志类型名(在配置文件中定义的)
*@paramstartTime查询日志的开始时间
*@paramendTime查询日志的结束时间
*@paramlogLevel查询日志的级别
*@paramuserName查询该用户的日志
*@parambufferNum日志反复器缓冲记录数
*@return结果集,日志反复器
*@since
*/
publicstaticLogIteratorread(StringlogType,DatestartTime,DateendTime,
intlogLevel,StringuserName,intbufferNum)
5.1.11.对于方法内部用throw语句抛出的异常,必须在方法的注释中标明,对于所调用的其他方法所抛出的异常,选择主要的在注释中说明。
对于非RuntimeException,即throws子句声明会抛出的异常,必须在方法的注释中标明。
说明:
异常注释用@exception或@throws表示,在JavaDoc中两者等价,但推荐用@exception标注Runtime异常,@throws标注非Runtime异常。
异常的注释必须说明该异常的含义及什么条件下抛出该异常。
5.1.12.*注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
5.1.13.*注释与所描述内容进行同样的缩排。
说明:
可使程序排版整齐,并方便注释的阅读与理解。
示例:
如下例子,排版不整齐,阅读稍感不方便。
publicvoidexample()
{
.)
{
programcode1
while(index { programcode2 }.)如果能被4整除,是闰年; 如果能被100整除,不是闰年.; 如果能被400整除,是闰年.。 6.命名规范 6.1.规则 6.1.1.包名采用域后缀倒置的加上自定义的包名,采用小写字母。 在部门内部应该规划好包名的范围,防止产生冲突。 部门内部产品使用部门的名称加上模块名称。 产品线的产品使用产品的名称加上模块的名称。 格式: .产品名.模块名称 .部门名称.项目名称 示例: 6.1.2.Relay模块包名通用日志模块包名类名和接口使用类意义完整的英文描述,每个英文单词的首字母使用大写、其余字母使用小写的大小写混合法。 示例: OrderInformation,CustomerList,LogManager,LogConfig 6.1.3.方法名使用类意义完整的英文描述: 第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。 示例: privatevoidcalculateRate(); publicvoidaddNewOrder(); 6.1.4.方法中,存取属性的方法采用setter和getter方法,动作方法采用动词和动宾结构。 格式: get+非布尔属性名() is+布尔属性名() set+属性名() 动词() 动词+宾语() 示例: publicStringgetType(); publicbooleanisFinished(); publicvoidsetVisible(boolean); publicvoidshow(); publicvoidaddKeyListener(Listener); 6.1.5.属性名使用意义完整的英文描述: 第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。 属性名不能与方法名相同。 示例: privatecustomerName; privateorderNumber; privatesmpSession; 6.1.6.常量名使用全大写的英文描述,英文单词之间用下划线分隔开,并且使用finalstatic修饰。 示例: publicfinalstaticintMAX_VALUE=1000; publicfinalstaticStringDEFAULT_START_DATE="2001-12-08"; 6.1.7.属性名可以和公有方法参数相同,不能和局部变量相同,引用非静态成员变量时使用this引用,引用静态成员变量时使用类名引用。 示例: publicclassPerson { privateStringname; privatestaticListproperties; publicvoidsetName(Stringname) { =name; } publicvoidsetProperties(Listproperties) { =properties; } } 6.2.建议 6.2.1.常用组件类的命名以组件名加上组件类型名结尾。 示例: Application类型的,命名以App结尾——MainApp Frame类型的,命名以Frame结尾——TopoFrame Panel类型的,建议命名以Panel结尾——CreateCircuitPanel Bean类型的,建议命名以Bean结尾——DataAccessBean EJB类型的,建议命名以EJB结尾——DBProxyEJB Applet类型的,建议命名以Applet结尾——PictureShowApplet 6.2.2.如果函数名超过15个字母,可采用以去掉元音字母的方法或者以行业内约定俗成的缩写方式缩写函数名。 示例: getCustomerInformation()改为getCustomerInfo() 6.2.3.准确地确定成员函数的存取控制符号,不是必须使用public属性的,请使用protected,不是必须使用protected,请使用private。 示例: protectedvoidsetUserName(),privatevoidcalculateRate() 6.2.4.含有集合意义的属性命名,尽量包含其复数的意义。 示例: customers,orderItems 7.编码规范 7.1.规则 7.1.1.*明确方法功能,精确(而不是近似)地实现方法设计。 一个函数仅完成一件功能,即使简单功能也应该编写方法实现。 说明: 虽然为仅用一两行就可完成的功能去编方法好象没有必要,但用方法可使功能明确化,增加程序可读性,亦可方便维护、测试。 7.1.2.应明确规定对接口方法参数的合法性检查应由方法的调用者负责还是由接口方法本身负责,缺省是由方法调用者负责。 说明: 对于模块间接口方法的参数的合法性检查这一问题,往往有两个极端现象,即: 要么是调用者和被调用者对参数均不作合法性检查,结果就遗漏了合法性检查这一必要的处理过程,造成问题隐患;要么就是调用者和被调用者均对参数进行合法性检查,这种情况虽不会造成问题,但产生了冗余代码,降低了效率。 7.1.3.明确类的功能,精确(而非近似)地实现类的设计。 一个类仅实现一组相近的功能。 说明: 划分类的时候,应该尽量把逻辑处理、数据和显示分离,实现类功能的单一性。 示例: 数据类不能包含数据处理的逻辑。 通信类不能包含显示处理的逻辑。 7.1.4.所有的数据类必须重载toString()方法,返回该类有意义的内容。 说明: 父类如果实现了比较合理的toString(),子类可以继承不必再重写。 示例: publicTopoNode { privateStringnodeName; publicStringtoString() { return"NodeName: "+nodeName; } } 7.1.5.数据库操作、IO操作等需要使用结束close()的对象必须在try-catch-finally的finally中close()。 示例: try { .... } catch(IOExceptionioe) { ... } finally { try { (); } catch(IOExceptionioe) { ... } } 7.1.6.异常捕获后,如果不对该异常进行处理,则应该纪录日志或者()。 说明: 若有特殊原因必须用注释加以说明。 示例: try { .... } catch(IOExceptionioe) { (); } 7.1.7.自己抛出的异常必须要填写详细的描述信息。 说明: 便于问题定位。 示例: thrownewIOException("Writingdataerror! Data: "+()); 7.1.8.运行期异常使用RuntimeException的子类来表示,不用在可能抛出异常的方法声明上加throws子句。 非运行期异常是从Exception继承而来,必须在方法声明上加throws子句。 说明: 非运行期异常是由外界运行环境决定异常抛出条件的异常,例如文件操作,可能受权限、磁盘空间大小的影响而失败,这种异常是程序本身无法避免的,需要调用者明确考虑该异常出现时该如何处理方法,因此非运行期异常必须有throws子句标出,不标出或者调用者不捕获该类型异常都会导致编译失败,从而防止程序员本身疏忽。 运行期异常是程序在运行过程中本身考虑不周导致的异常,例如传入错误的参数等。 抛出运行期异常的目的是防止异常扩散,导致定位困难。 因此在做异常体系设计时要根据错误的性质合理选择自定义异常的继承关系。 还有一种异常是Error继承而来的,这种异常由虚拟机自己维护,表示发生了致命错误,程序无法继续运行例如内存不足。 我们自己的程序不应该捕获这种异常,并且也不应该创建该种类型的异常。 7.1.9.在程序中使用异常处理还是使用错误返回码处理,根据是否有利于程序结构来确定,并且异常和错误码不应该混合使用,推荐使用异常。 说明: 一个系统或者模块应该统一规划异常类型和返回码的含义。 但是不能用异常来做一般流程处理的方式,不要过多地使用异常,异常的处理效率比条件分支低,而且异常的跳转流程难以预测。 7.1.10.*注意运算符的优先级,并用括号明确表达式的操作顺序,避免使用默认优先级。 说明: 防止阅读程序时产生误解,防止因默认的优先级与设计思想不符而导致程序出错。 示例: 下列语句中的表达式 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)造成了判断条件出错。 7.1.11.*避免使用不易理解的数字,用有意义的标识来替代。 涉及物理状态或者含有物理意义的常量,不应直接使用数字,必须用有意义的静态变量来代替。 示例: 如下的程序可读性差。 if(state==0) { state=1; ...... } 如下程序可读性好: publicint[]getIndex() { .... } 7.1.12.调试代码的时候,不要使用和进行打印,应该使用一个包含统一开关的测试类进行统一打印。 说明: 代码发布的时候可以统一关闭调试代码,定位问题的时候又可以打开开关。 7.1.13.用调测开关来切换软件的DEBUG版和正式版,而不要同时存在正式版本和DEBUG版本的不同源文件,以减少维护的难度。 7.2.建议 7.2.1.记录异常不要保存(),而要记录()。 示例: NullPointException抛出时常常描述为空,这样往往看不出是出了什么错。 7.2.2.一个方法不应抛出太多类型的异常。 说明: 如果程序中需要分类处理,则将异常根据分类组织成继承关系。 如果确实有很多异常类型首先考虑用异常描述来区别,throws/exception子句标明的异常最好不要超过三个。 7.2.3.异常捕获尽量不要直接catch(Exceptionex),应该把异常细分处理。 7.2.4.*如果多段代码重复做同一件事情,那么在方法的划分上可能存在问题。 说明: 若此段代码各语句之间有实
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 华为 Java 语言 编码 规范