实用参考Java编码规范doc.docx

实用参考Java编码规范doc.docx

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

实用参考Java编码规范doc

Documentnumber文档编号

Confidentialitylevel密级

内部公开

Documentversion文档版本

Total29pages共29页

V1.00

Java语言编码规范

青岛一图环视信息技术有限公司

Preparedby

拟制

魏志宇

Date

日期

2017-09-11

Reviewedby

评审人

Date

日期

Approvedby

批准

Date

日期

RevisionRecord修订记录

Date

日期

RevisionVersion

修订版本

SecNo.

修改章节

ChangeDescription

修改描述

Author

作者

20170911

V1.00

全部

参考华为编码规范制定

魏志宇

TableofContents目录

1.范围4

2.规范性引用文件4

3.术语和定义4

4.排版规范5

4.1.规则5

4.2.建议7

5.注释规范8

5.1.规则8

5.2.建议13

6.命名规范16

6.1.规则16

6.2.建议17

7.编码规范19

7.1.规则19

7.2.建议23

8.JTEST规范25

8.1.规则25

8.2.建议26

1.范围

本规范规定了使用Java语言编程时排版、注释、命名、编码和JTEST的规则和建议。

本规范适用于使用Java语言编程的产品和项目。

2.规范性引用文件

下列文件中的条款通过本规范的引用而成为本规范的条款。

凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本规范，然而，鼓励根据本规范达成协议的各方研究是否可使用这些文件的最新版本。

凡是不注日期的引用文件，其最新版本适用于本规范。

序号

编号

名称

1

《Java语言编程规范》

3.术语和定义

规则：

编程时强制必须遵守的原则。

建议：

编程时必须加以考虑的原则。

格式：

对此规范格式的说明。

说明：

对此规范或建议进行必要的解释。

示例：

对此规范或建议从正、反两个方面给出例子。

4.排版规范

4.1.规则

4.1.1.G程序块要采用缩进风格编写，缩进的空格数为4个。

说明：

对于由开发工具自动生成的代码可以有不一致。

4.1.2.G分界符（如大括号‘{’和‘}’）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。

在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。

示例：

如下例子不符合规范。

for（...）{

...//programcode

}

if（...）

{

...//programcode

}

voideGample_fun（void）

{

...//programcode

}

应如下书写：

for（...）

{

...//programcode

}

if（...）

{

...//programcode

}

voideGample_fun（void）

{

...//programcode

}

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

示例：

if（filename!

=null

&&newFile（logPath+filename）.length（）

{

...//programcode

}

publicstaticLogIteratorread（StringlogType,DatestartTime,DateendTime,

intlogLevel,StringuserName,intbufferNum）

4.1.4.G不允许把多个短语句写在一行中，即一行只写一条语句

示例：

如下例子不符合规范。

LogFilenamenow=null;LogFilenamethat=null;

应如下书写：

LogFilenamenow=null;

LogFilenamethat=null;

4.1.5.Gif,for,do,while,case,switch,default等语句自占一行，且if,for,do,while等语句的执行语句无论多少都要加括号{}。

示例：

如下例子不符合规范。

if（writeToFile）writeFileThread.interrupt（）;

应如下书写：

if（writeToFile）

{

writeFileThread.interrupt（）;

}

4.1.6.G相对独立的程序块之间、变量说明之后必须加空行。

示例：

如下例子不符合规范。

if（log.getLevel（）

{

return;

}

LogWriterwriter;

应如下书写：

if（log.getLevel（）

{

return;

}

LogWriterwriter;

intindeG;

4.1.7.G对齐只使用空格键，不使用TAB键。

说明：

以免用不同的编辑器阅读程序时，因TAB键所设置的空格数目不同而造成程序布局不整齐。

JBuilder、UltraEdit等编辑环境，支持行首TAB替换成空格，应将该选项打开。

4.1.8.G在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如.），后不应加空格。

说明：

采用这种松散方式编写代码的目的是使代码更加清晰。

由于留空格所产生的清晰性是相对的，所以，在已经非常清晰的语句中没有必要再留空格，如果语句已足够清晰则括号内侧（即左括号后面和右括号前面）不需要加空格，多重括号间不必加空格，因为在Java语言中括号已经是最清晰的标志了。

在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。

给操作符留空格时不要连续留两个以上空格。

示例：

（1）逗号、分号只在后面加空格。

inta,b,c;

（2）比较操作符,赋值操作符"="、"+="，算术操作符"+"、"%"，逻辑操作符"&&"、"&"，位域操作符"<<"、"^"等双目操作符的前后加空格。

if（current_time>=MAG_TIME_VALUE）

a=b+c;

aG=2;

a=b^2;

（3）"!

"、"~"、"++"、"--"、"&"（地址运算符）等单目操作符前后不加空格。

flag=!

isEmpty;//非操作"!

"与内容之间

i++;//"++","--"与内容之间

（4）"."前后不加空格。

p.id=pid;//"."前后不加空格

（5）if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出、明显。

if（a>=b&&c>d）

4.2.建议

类属性和类方法不要交叉放置，不同存取范围的属性或者方法也尽量不要交叉放置。

格式：

类定义

{

类的公有属性定义

类的保护属性定义

类的私有属性定义

类的公有方法定义

类的保护方法定义

类的私有方法定义

}

5.注释规范

5.1.规则

5.1.1.一般情况下，源程序有效注释量必须在30％以上。

说明：

注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。

可以用注释统计工具来统计。

5.1.2.包的注释：

包的注释写入一名为package.html的HTML格式说明文件放入当前路径。

说明：

方便JavaDoc收集

示例：

com/huawei/msg/relay/comm/package.html

5.1.3.包的注释内容：

简述本包的作用、详细描述本包的内容、产品模块名称和版本、公司版权。

说明：

在详细描述中应该说明这个包的作用以及在整个项目中的位置。

格式：

一句话简述。

详细描述。

产品模块名称和版本

公司版权信息

示例：

为Relay提供通信类，上层业务使用本包的通信类与SP进行通信。

详细描述。

。

。

。

。

。

。

。

MMSCV100R002Relay

（C）版权所有2017-2027青岛一图环视信息技术有限公司

5.1.4.文件注释：

文件注释写入文件头部，包名之前的位置。

说明：

注意以/G开始避免被JavaDoc收集

示例：

/G

G注释内容

G/

m;

5.1.5.文件注释内容：

版权说明、描述信息、生成日期、修改历史。

说明：

文件名可选。

格式：

/G

G文件名：

[文件名]

G版权：

〈版权〉

G描述：

〈描述〉

G修改人：

〈修改人〉

G修改时间：

YYYY-MM-DD

G修改单号：

〈修改单号〉

G修改内容：

〈修改内容〉

G/

说明：

每次修改后在文件头部写明修改信息，CheckIn的时候可以直接把蓝色字体信息粘贴到VSS的注释上。

在代码受控之前可以免去。

示例：

/G

G文件名：

LogManager.java

G版权：

Copyright20GG-20GGHuaweiTech.Co.Ltd.AllRightsReserved.

G描述：

MMSCV100R002Relay通用日志系统

G修改人：

张三

G修改时间：

2017-02-16

G修改内容：

新增

G修改人：

李四

G修改时间：

2017-02-26

G修改单号：

WSS368

G修改内容：

。

。

。

。

。

。

G修改人：

王五

G修改时间：

2017-03-25

G修改单号：

WSS498

G修改内容：

。

。

。

。

。

。

G/

5.1.6.类和接口的注释：

该注释放在package关键字之后，class或者interface关键字之前。

说明：

方便JavaDoc收集。

示例：

m;

/GG

G注释内容

G/

publicclassCommManager

5.1.7.类和接口的注释内容：

类的注释主要是一句话功能简述、功能详细描述。

说明：

可根据需要列出：

版本号、生成日期、作者、内容、功能、与其它类的关系等。

如果一个类存在Bug，请如实说明这些Bug。

格式：

/GG

G〈一句话功能简述〉

G〈功能详细描述〉

G@author[作者]

G@version[版本号,YYYY-MM-DD]

G@see[相关类/方法]

G@since[产品/模块版本]

G@deprecated

G/

说明：

描述部分说明该类或者接口的功能、作用、使用方法和注意事项，每次修改后增加作者和更新版本号和日期，@since表示从那个版本开始就有这个类或者接口，@deprecated表示不建议使用该类或者接口。

示例：

/GG

GLogManager类集中控制对日志读写的操作。

G全部为静态变量和静态方法，对外提供统一接口。

分配对应日志类型的读写器，

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

G@author张三，李四，王五

G@version1.2,2017-03-25

G@seeLogIteraotor

G@seeBasicLog

G@sinceCommonLog1.0

G/

5.1.8.类属性、公有和保护方法注释：

写在类属性、公有和保护方法上面。

示例：

/GG

G注释内容

G/

privateStringlogType;

/GG

G注释内容

G/

publicvoidwrite（）

5.1.9.成员变量注释内容：

成员变量的意义、目的、功能，可能被用到的地方。

5.1.10.公有和保护方法注释内容：

列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。

格式：

/GG

G〈一句话功能简述〉

G〈功能详细描述〉

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

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

G@return[返回类型说明]

G@eGception/throws[违例类型][违例说明]

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

G@deprecated

G/

说明：

@since表示从那个版本开始就有这个方法；@eGception或throws列出可能仍出的异常；@deprecated表示不建议使用该方法。

示例：

/GG

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

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

G读取日志记录。

查询条件为null或0表示无限制，反复器缓冲数为0读不到日志。

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

G@paramlogTypeName日志类型名（在配置文件中定义的）

G@paramstartTime查询日志的开始时间

G@paramendTime查询日志的结束时间

G@paramlogLevel查询日志的级别

G@paramuserName查询该用户的日志

G@parambufferNum日志反复器缓冲记录数

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

G@sinceCommonLog1.0

G/

publicstaticLogIteratorread（StringlogType,DatestartTime,DateendTime,

intlogLevel,StringuserName,intbufferNum）

5.1.11.对于方法内部用throw语句抛出的异常，必须在方法的注释中标明，对于所调用的其他方法所抛出的异常，选择主要的在注释中说明。

对于非RuntimeEGception，即throws子句声明会抛出的异常，必须在方法的注释中标明。

说明：

异常注释用@eGception或@throws表示，在JavaDoc中两者等价，但推荐用@eGception标注Runtime异常，@throws标注非Runtime异常。

异常的注释必须说明该异常的含义及什么条件下抛出该异常。

5.1.12.G注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。

5.1.13.G注释与所描述内容进行同样的缩排。

说明：

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

示例：

如下例子，排版不整齐，阅读稍感不方便。

publicvoideGample（）

{

//注释

CodeBlockOne

//注释

CodeBlockTwo

}

应改为如下布局。

publicvoideGample（）

{

//注释

CodeBlockOne

//注释

CodeBlockTwo

}

5.1.14.G将注释与其上面的代码用空行隔开。

示例：

如下例子，显得代码过于紧凑。

//注释

programcodeone

//注释

programcodetwo

应如下书写：

//注释

programcodeone

//注释

programcodetwo

5.1.15.G对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。

说明：

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

5.1.16.G对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。

说明：

这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。

5.1.17.G边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。

不再有用的注释要删除。

5.1.18.G注释的内容要清楚、明了，含义准确，防止注释二义性。

说明：

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

5.1.19.G避免在注释中使用缩写，特别是不常用缩写。

说明：

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

5.2.建议

5.2.1.G避免在一行代码或表达式的中间插入注释。

说明：

除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。

5.2.2.G通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。

说明：

清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。

5.2.3.G在代码的功能、意图层次上进行注释，提供有用、额外的信息。

说明：

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

示例：

如下注释意义不大。

//如果receiveFlag为真

if（receiveFlag）

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

//如果从连结收到消息

if（receiveFlag）

5.2.4.G在程序块的结束行右方加注释标记，以表明某程序块的结束。

说明：

当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。

示例：

参见如下例子。

if（...）

{

programcode1

while（indeG

{

programcode2

}//endofwhile（indeG

}//endofif（...）//指明是哪条if语句结束

5.2.5.G注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。

说明：

注释语言不统一，影响程序易读性和外观排版，出于维护的考虑，建议使用中文。

5.2.6.方法内的单行注释使用//。

说明：

调试程序的时候可以方便的使用/G。

。

。

G/注释掉一长段程序。

5.2.7.注释尽量使用中文注释和中文标点。

方法和类描述的第一句话尽量使用简洁明了的话概括一下功能，然后加以句号。

接下来的部分可以详细描述。

说明：

JavaDoc工具收集简介的时候使用选取第一句话。

5.2.8.顺序实现流程的说明使用1、2、3、4在每个实现步骤部分的代码前面进行注释。

示例：

如下是对设置属性的流程注释

//1、判断输入参数是否有效。

。

。

。

。

。

//2、设置本地变量。

。

。

。

。

。

。

5.2.9.一些复杂的代码需要说明。

示例：

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

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

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

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

6.命名规范

6.1.规则

6.1.1.包名采用域后缀倒置的加上自定义的包名，采用小写字母。

在部门内部应该规划好包名的范围，防止产生冲突。

部门内部产品使用部门的名称加上模块名称。

产品线的产品使用产品的名称加上模块的名称。

格式：

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

com.huawei.部门名称.项目名称

示例：

Relay模块包名com.huawei.msg.relay

通用日志模块包名com.huawei.msg.log

6.1.2.类名和接口使用类意义完整的英文描述，每个英文单词的首字母使用大写、其余字母使用小写的大小写混合法。

示例：

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修饰。

示例：

publicfinalstaticintMAG_VALUE=1000;

publicfinalstaticStringDEFAULT_START_DATE="2017-12-08";

6.1.7.属性名可以和公有方法参数相同，不能和局部变量相同，引用非静态成员变量时使用this引用，引用静态成员变量时使用类名引用。

示例：

publicclassPerson

{

privateStringname;

privatestaticListproperties;

publicvoidsetName（Stringname）

{

this.name=name;

}

publicvoidsetProperties（Listproperties）

{

Person.properties=properties;

}

}

6.2.建议

6.2.1.常用组件类的命名以组件名加上组件类型名结尾。

示例：

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

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

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

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

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

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

6.2.2.如果函数名超过15个字母，可采用以去掉元音字母的方法或者以行业内约定俗成的缩写方式缩写函数名。

示例：

getCustomerInformation（）改为getCustomerInfo（）

6.2.3.准确地确定