标签：
|
Document number 文档编号 |
Confidentiality level 密级 |
|
|
内部公开 |
|
Document version 文档版本 |
Total 29 pages 共 29 页 |
|
V1.00 |
Java语言编码规范
|
Prepared by 拟制 |
|
Date 日期 |
yyyy-mm-dd |
|
Reviewed by 评审人 |
|
Date 日期 |
yyyy-mm-dd |
|
Approved by 批准 |
|
Date 日期 |
yyyy-mm-dd |
Revision Record 修订记录
|
Date 日期 |
Revision Version 修订版本 |
Sec No. 修改章节 |
Change Description 修改描述 |
Author 作者 |
|
|||||
|
|
yyyy-mm-dd |
Vx.xx |
|
|
|
|||||
|
|
|
|
|
|
|
|||||
|
|
|
|
|
|
|
|||||
|
|
|
|
|
|
|
|||||
|
|
|
|
|
|
|
|||||
Table of Contents 目录
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
本规范规定了使用Java语言编程时排版、注释、命名、编码和JTEST的规则和建议。
本规范适用于使用Java语言编程的产品和项目。
下列文件中的条款通过本规范的引用而成为本规范的条款。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本规范，然而，鼓励根据本规范达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件，其最新版本适用于本规范。
|
序号 |
编号 |
名称 |
|
1 |
公司- DKBA1040-2001.12 |
《Java语言编程规范》 |
规则：编程时强制必须遵守的原则。
建议：编程时必须加以考虑的原则。
格式：对此规范格式的说明。
说明：对此规范或建议进行必要的解释。
示例：对此规范或建议从正、反两个方面给出例子。
说明：对于由开发工具自动生成的代码可以有不一致。
示例：如下例子不符合规范。
for (...) {
... // program code
}
if (...)
{
... // program code
}
void example_fun( void )
{
... // program code
}
应如下书写：
for (...)
{
... // program code
}
if (...)
{
... // program code
}
void example_fun( void )
{
... // program code
}
示例：
if (filename != null
&& new File(logPath + filename).length() < LogConfig.getFileSize())
{
... // program code
}
public static LogIterator read(String logType, Date startTime, Date endTime,
int logLevel, String userName, int bufferNum)
示例：如下例子不符合规范。
LogFilename now = null; LogFilename that = null;
应如下书写：
LogFilename now = null;
LogFilename that = null;
示例：如下例子不符合规范。
if(writeToFile) writeFileThread.interrupt();
应如下书写：
if(writeToFile)
{
writeFileThread.interrupt();
}
示例：如下例子不符合规范。
if(log.getLevel() < LogConfig.getRecordLevel())
{
return;
}
LogWriter writer;
应如下书写：
if(log.getLevel() < LogConfig.getRecordLevel())
{
return;
}
LogWriter writer;
int index;
说明：以免用不同的编辑器阅读程序时，因TAB键所设置的空格数目不同而造成程序布局不整齐。JBuilder、UltraEdit等编辑环境，支持行首TAB替换成空格，应将该选项打开。
说明：采用这种松散方式编写代码的目的是使代码更加清晰。
由于留空格所产生的清晰性是相对的，所以，在已经非常清晰的语句中没有必要再留空格，如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格，多重括号间不必加空格，因为在Java语言中括号已经是最清晰的标志了。
在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。给操作符留空格时不要连续留两个以上空格。
示例：
（1） 逗号、分号只在后面加空格。
int a, b, c;
（2） 比较操作符, 赋值操作符"="、 "+="，算术操作符"+"、"%"，逻辑操作符"&&"、"&"，位域操作符"<<"、"^"等双目操作符的前后加空格。
if (current_time >= MAX_TIME_VALUE)
a = b + c;
a *= 2;
a = b ^ 2;
（3） "!"、"~"、"++"、"--"、"&"（地址运算符）等单目操作符前后不加空格。
flag = !isEmpty; // 非操作"!"与内容之间
i++; // "++","--"与内容之间
（4） "."前后不加空格。
p.id = pid; // "."前后不加空格
（5） if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出、明显。
if (a >= b && c > d)
类属性和类方法不要交叉放置，不同存取范围的属性或者方法也尽量不要交叉放置。
格式：
类定义
{
类的公有属性定义
类的保护属性定义
类的私有属性定义
类的公有方法定义
类的保护方法定义
类的私有方法定义
}
说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。可以用注释统计工具来统计。
说明：方便JavaDoc收集
示例：
com/huawei/msg/relay/comm/package.html
说明：在详细描述中应该说明这个包的作用以及在整个项目中的位置。
格式：
<html>
<body>
<p>一句话简述。
<p>详细描述。
<p>产品模块名称和版本
<br>公司版权信息
</body>
</html>
示例：
<html>
<body>
<P>为 Relay 提供通信类，上层业务使用本包的通信类与SP进行通信。
<p>详细描述。。。。。。。。
<p>MMSC V100R002 Relay
<br>(C) 版权所有 2002-2007 文思创新技术有限公司
</body>
</html>
说明：注意以 /* 开始避免被 JavaDoc 收集
示例：
/*
* 注释内容
*/
package com.huawei.msg.relay.comm;
说明：文件名可选。
格式：
/*
* 文件名：[文件名]
* 版权：〈版权〉
* 描述：〈描述〉
* 修改人：〈修改人〉
* 修改时间：YYYY-MM-DD
* 修改单号：〈修改单号〉
* 修改内容：〈修改内容〉
*/
说明：每次修改后在文件头部写明修改信息，CheckIn的时候可以直接把蓝色字体信息粘贴到VSS的注释上。在代码受控之前可以免去。
示例：
/*
* 文件名：LogManager.java
* 版权：Copyright 2002-2007 Huawei Tech. Co. Ltd. All Rights Reserved.
* 描述： MMSC V100R002 Relay 通用日志系统
* 修改人： 张三
* 修改时间：2001-02-16
* 修改内容：新增
* 修改人： 李四
* 修改时间：2001-02-26
* 修改单号：WSS368
* 修改内容：。。。。。。
* 修改人： 王五
* 修改时间：2001-03-25
* 修改单号：WSS498
* 修改内容：。。。。。。
*/
说明：方便JavaDoc收集。
示例：
package com.huawei.msg.relay.comm;
/**
* 注释内容
*/
public class CommManager
说明：可根据需要列出：版本号、生成日期、作者、内容、功能、与其它类的关系等。 如果一个类存在Bug，请如实说明这些Bug。
格式：
/**
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @author [作者]
* @version [版本号, YYYY-MM-DD]
* @see [相关类/方法]
* @since [产品/模块版本]
* @deprecated
*/
说明：描述部分说明该类或者接口的功能、作用、使用方法和注意事项，每次修改后增加作者和更新版本号和日期，@since 表示从那个版本开始就有这个类或者接口，@deprecated 表示不建议使用该类或者接口。
示例：
/**
* LogManager 类集中控制对日志读写的操作。
* 全部为静态变量和静态方法，对外提供统一接口。分配对应日志类型的读写器，
* 读取或写入符合条件的日志纪录。
* @author 张三，李四，王五
* @version 1.2, 2001-03-25
* @see LogIteraotor
* @see BasicLog
* @since CommonLog1.0
*/
示例：
/**
* 注释内容
*/
private String logType;
/**
* 注释内容
*/
public void write()
格式：
/**
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @param [参数1] [参数1说明]
* @param [参数2] [参数2说明]
* @return [返回类型说明]
* @exception/throws [违例类型] [违例说明]
* @see [类、类#方法、类#成员]
* @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 CommonLog1.0
*/
public static LogIterator read(String logType, Date startTime, Date endTime,
int logLevel, String userName, int bufferNum)
说明：异常注释用@exception或@throws表示，在JavaDoc中两者等价，但推荐用@exception标注Runtime异常，@throws标注非Runtime异常。异常的注释必须说明该异常的含义及什么条件下抛出该异常。
说明：可使程序排版整齐，并方便注释的阅读与理解。
示例：如下例子，排版不整齐，阅读稍感不方便。
public void example( )
{
// 注释
CodeBlock One
// 注释
CodeBlock Two
}
应改为如下布局。
public void example( )
{
// 注释
CodeBlock One
// 注释
CodeBlock Two
}
示例：如下例子，显得代码过于紧凑。
//注释
program code one
//注释
program code two
应如下书写：
//注释
program code one
//注释
program code two
说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。
说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。
说明：错误的注释不但无益反而有害。
说明：在使用缩写时或之前，应对缩写进行必要的说明。
说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。
说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。
说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。
示例：如下注释意义不大。
// 如果 receiveFlag 为真
if (receiveFlag)
而如下的注释则给出了额外有用的信息。
// 如果从连结收到消息
if (receiveFlag)
说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。
示例：参见如下例子。
if (...)
{
program code1
while (index < MAX_INDEX)
{
program code2
} // end of while (index < MAX_INDEX) // 指明该条while语句结束
} // end of if (...) // 指明是哪条if语句结束
说明：注释语言不统一，影响程序易读性和外观排版，出于维护的考虑，建议使用中文。
说明：调试程序的时候可以方便的使用 /* 。。。*/ 注释掉一长段程序。
说明：JavaDoc工具收集简介的时候使用选取第一句话。
示例：如下是对设置属性的流程注释
//1、 判断输入参数是否有效。
。。。。。
// 2、设置本地变量。
。。。。。。
示例：这里主要是对闰年算法的说明。
//1. 如果能被4整除，是闰年；
//2. 如果能被100整除，不是闰年.；
//3. 如果能被400整除，是闰年.。
格式：
com.huawei.产品名.模块名称
com.huawei.部门名称. 项目名称
示例：
Relay模块包名 com.huawei.msg.relay
通用日志模块包名 com.huawei.msg.log
示例：OrderInformation, CustomerList, LogManager, LogConfig
示例：
private void calculateRate();
public void addNewOrder();
格式：
get + 非布尔属性名()
is + 布尔属性名()
set + 属性名()
动词()
动词 + 宾语()
示例：
public String getType();
public boolean isFinished();
public void setVisible(boolean);
public void show();
public void addKeyListener(Listener);
示例：
private customerName;
private orderNumber;
private smpSession;
示例：
public final static int MAX_VALUE = 1000;
public final static String DEFAULT_START_DATE = "2001-12-08";
示例：
public class Person
{
private String name;
private static List properties;
public void setName (String name)
{
this.name = name;
}
public void setProperties (List properties)
{
Person.properties = properties;
}
}
示例：
Application 类型的，命名以App 结尾——MainApp
Frame 类型的，命名以Frame 结尾——TopoFrame
Panel 类型的，建议命名以Panel 结尾——CreateCircuitPanel
Bean 类型的，建议命名以Bean 结尾——DataAccessBean
EJB 类型的，建议命名以EJB 结尾——DBProxyEJB
Applet 类型的，建议命名以Applet 结尾——PictureShowApplet
示例：getCustomerInformation() 改为 getCustomerInfo()
示例：protected void setUserName(), private void calculateRate()
示例：customers, orderItems
说明：虽然为仅用一两行就可完成的功能去编方法好象没有必要，但用方法可使功能明确化，增加程序可读性，亦可方便维护、测试。
说明：对于模块间接口方法的参数的合法性检查这一问题，往往有两个极端现象，即：要么是调用者和被调用者对参数均不作合法性检查，结果就遗漏了合法性检查这一必要的处理过程，造成问题隐患；要么就是调用者和被调用者均对参数进行合法性检查，这种情况虽不会造成问题，但产生了冗余代码，降低了效率。
说明：划分类的时候，应该尽量把逻辑处理、数据和显示分离，实现类功能的单一性。
示例：
数据类不能包含数据处理的逻辑。
通信类不能包含显示处理的逻辑。
说明： 父类如果实现了比较合理的toString() ，子类可以继承不必再重写。
示例：
public TopoNode
{
private String nodeName;
public String toString()
{
return "NodeName : " + nodeName;
}
}
示例：
try
{
// ... ...
}
catch(IOException ioe)
{
//... ...
}
finally
{
try
{
out.close();
}
catch (IOException ioe)
{
//... ...
}
}
说明：若有特殊原因必须用注释加以说明。
示例：
try
{
//.... ...
}
catch (IOException ioe)
{
ioe.printStackTrace ();
}
说明：便于问题定位。
示例：
throw new IOException("Writing data error! Data: " + data.toString());
说明：
非运行期异常是由外界运行环境决定异常抛出条件的异常，例如文件操作，可能受权限、磁盘空间大小的影响而失败，这种异常是程序本身无法避免的，需要调用者明确考虑该异常出现时该如何处理方法，因此非运行期异常必须有throws子句标出，不标出或者调用者不捕获该类型异常都会导致编译失败，从而防止程序员本身疏忽。
运行期异常是程序在运行过程中本身考虑不周导致的异常，例如传入错误的参数等。抛出运行期异常的目的是防止异常扩散，导致定位困难。因此在做异常体系设计时要根据错误的性质合理选择自定义异常的继承关系。
还有一种异常是Error 继承而来的，这种异常由虚拟机自己维护，表示发生了致命错误，程序无法继续运行例如内存不足。我们自己的程序不应该捕获这种异常，并且也不应该创建该种类型的异常。
说明：
一个系统或者模块应该统一规划异常类型和返回码的含义。
但是不能用异常来做一般流程处理的方式，不要过多地使用异常，异常的处理效率比条件分支低，而且异常的跳转流程难以预测。
说明：防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。
示例：
下列语句中的表达式
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）造成了判断条件出错。
示例：如下的程序可读性差。
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
}
说明：使用int index[] 格式使程序的可读性较差
示例：
如下程序可读性差：
public int getIndex()[]
{
....
}
如下程序可读性好：
public int[] getIndex()
{
....
}
说明：代码发布的时候可以统一关闭调试代码，定位问题的时候又可以打开开关。
示例：NullPointException抛出时常常描述为空，这样往往看不出是出了什么错。
说明： 如果程序中需要分类处理，则将异常根据分类组织成继承关系。如果确实有很多异常类型首先考虑用异常描述来区别，throws/exception子句标明的异常最好不要超过三个。
说明：若此段代码各语句之间有实质性关联并且是完成同一件功能的，那么可考虑把此段代码构造成一个新的方法。
说明：主要类包括：
1、能完成独立功能的类，如通讯。
2、具有完整界面的类，如一个对话框、一个窗口、一个帧等。
3、JavaBean 类。
示例：
public static void main(String[] arguments)
{
CreateCircuitDialog circuitDialog1 = new CreateCircuitDialog (null,
"Ciruit", false);
circuitDialog1.setVisible(true);
}
说明：由于集合保存了对象的句柄，虚拟机的垃圾收集器就不会回收。
说明：便于程序阅读和查找。
示例：矩形的长与宽关系较密切，放在一起。
rect.length = 10;
rect.width = 5;
说明：高技巧语句不等于高效率的程序，实际上程序的效率关键在于算法。
继承层次 5层
类的行数 1000行（包含{}）
类的属性 10个
|
Document number 文档编号 |
Confidentiality level 密级 |
|
|
内部公开 |
|
Document version 文档版本 |
Total 29 pages 共 29 页 |
|
V1.00 |
Java语言编码规范
|
Prepared by 拟制 |
|
Date 日期 |
yyyy-mm-dd |
|
Reviewed by 评审人 |
|
Date 日期 |
yyyy-mm-dd |
|
Approved by 批准 |
|
Date 日期 |
yyyy-mm-dd |
Revision Record 修订记录
|
Date 日期 |
Revision Version 修订版本 |
Sec No. 修改章节 |
Change Description 修改描述 |
Author 作者 |
|
|||||
|
|
yyyy-mm-dd |
Vx.xx |
|
|
|
|||||
|
|
|
|
|
|
|
|||||
|
|
|
|
|
|
|
|||||
|
|
|
|
|
|
|
|||||
|
|
|
|
|
|
|
|||||
Table of Contents 目录
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
本规范规定了使用Java语言编程时排版、注释、命名、编码和JTEST的规则和建议。
本规范适用于使用Java语言编程的产品和项目。
下列文件中的条款通过本规范的引用而成为本规范的条款。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本规范，然而，鼓励根据本规范达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件，其最新版本适用于本规范。
|
序号 |
编号 |
名称 |
|
1 |
公司- DKBA1040-2001.12 |
《Java语言编程规范》 |
规则：编程时强制必须遵守的原则。
建议：编程时必须加以考虑的原则。
格式：对此规范格式的说明。
说明：对此规范或建议进行必要的解释。
示例：对此规范或建议从正、反两个方面给出例子。
说明：对于由开发工具自动生成的代码可以有不一致。
示例：如下例子不符合规范。
for (...) {
... // program code
}
if (...)
{
... // program code
}
void example_fun( void )
{
... // program code
}
应如下书写：
for (...)
{
... // program code
}
if (...)
{
... // program code
}
void example_fun( void )
{
... // program code
}
示例：
if (filename != null
&& new File(logPath + filename).length() < LogConfig.getFileSize())
{
... // program code
}
public static LogIterator read(String logType, Date startTime, Date endTime,
int logLevel, String userName, int bufferNum)
示例：如下例子不符合规范。
LogFilename now = null; LogFilename that = null;
应如下书写：
LogFilename now = null;
LogFilename that = null;
示例：如下例子不符合规范。
if(writeToFile) writeFileThread.interrupt();
应如下书写：
if(writeToFile)
{
writeFileThread.interrupt();
}
示例：如下例子不符合规范。
if(log.getLevel() < LogConfig.getRecordLevel())
{
return;
}
LogWriter writer;
应如下书写：
if(log.getLevel() < LogConfig.getRecordLevel())
{
return;
}
LogWriter writer;
int index;
说明：以免用不同的编辑器阅读程序时，因TAB键所设置的空格数目不同而造成程序布局不整齐。JBuilder、UltraEdit等编辑环境，支持行首TAB替换成空格，应将该选项打开。
说明：采用这种松散方式编写代码的目的是使代码更加清晰。
由于留空格所产生的清晰性是相对的，所以，在已经非常清晰的语句中没有必要再留空格，如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格，多重括号间不必加空格，因为在Java语言中括号已经是最清晰的标志了。
在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。给操作符留空格时不要连续留两个以上空格。
示例：
（1） 逗号、分号只在后面加空格。
int a, b, c;
（2） 比较操作符, 赋值操作符"="、 "+="，算术操作符"+"、"%"，逻辑操作符"&&"、"&"，位域操作符"<<"、"^"等双目操作符的前后加空格。
if (current_time >= MAX_TIME_VALUE)
a = b + c;
a *= 2;
a = b ^ 2;
（3） "!"、"~"、"++"、"--"、"&"（地址运算符）等单目操作符前后不加空格。
flag = !isEmpty; // 非操作"!"与内容之间
i++; // "++","--"与内容之间
（4） "."前后不加空格。
p.id = pid; // "."前后不加空格
（5） if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出、明显。
if (a >= b && c > d)
类属性和类方法不要交叉放置，不同存取范围的属性或者方法也尽量不要交叉放置。
格式：
类定义
{
类的公有属性定义
类的保护属性定义
类的私有属性定义
类的公有方法定义
类的保护方法定义
类的私有方法定义
}
说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。可以用注释统计工具来统计。
说明：方便JavaDoc收集
示例：
com/huawei/msg/relay/comm/package.html
说明：在详细描述中应该说明这个包的作用以及在整个项目中的位置。
格式：
<html>
<body>
<p>一句话简述。
<p>详细描述。
<p>产品模块名称和版本
<br>公司版权信息
</body>
</html>
示例：
<html>
<body>
<P>为 Relay 提供通信类，上层业务使用本包的通信类与SP进行通信。
<p>详细描述。。。。。。。。
<p>MMSC V100R002 Relay
<br>(C) 版权所有 2002-2007 文思创新技术有限公司
</body>
</html>
说明：注意以 /* 开始避免被 JavaDoc 收集
示例：
/*
* 注释内容
*/
package com.huawei.msg.relay.comm;
说明：文件名可选。
格式：
/*
* 文件名：[文件名]
* 版权：〈版权〉
* 描述：〈描述〉
* 修改人：〈修改人〉
* 修改时间：YYYY-MM-DD
* 修改单号：〈修改单号〉
* 修改内容：〈修改内容〉
*/
说明：每次修改后在文件头部写明修改信息，CheckIn的时候可以直接把蓝色字体信息粘贴到VSS的注释上。在代码受控之前可以免去。
示例：
/*
* 文件名：LogManager.java
* 版权：Copyright 2002-2007 Huawei Tech. Co. Ltd. All Rights Reserved.
* 描述： MMSC V100R002 Relay 通用日志系统
* 修改人： 张三
* 修改时间：2001-02-16
* 修改内容：新增
* 修改人： 李四
* 修改时间：2001-02-26
* 修改单号：WSS368
* 修改内容：。。。。。。
* 修改人： 王五
* 修改时间：2001-03-25
* 修改单号：WSS498
* 修改内容：。。。。。。
*/
说明：方便JavaDoc收集。
示例：
package com.huawei.msg.relay.comm;
/**
* 注释内容
*/
public class CommManager
说明：可根据需要列出：版本号、生成日期、作者、内容、功能、与其它类的关系等。 如果一个类存在Bug，请如实说明这些Bug。
格式：
/**
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @author [作者]
* @version [版本号, YYYY-MM-DD]
* @see [相关类/方法]
* @since [产品/模块版本]
* @deprecated
*/
说明：描述部分说明该类或者接口的功能、作用、使用方法和注意事项，每次修改后增加作者和更新版本号和日期，@since 表示从那个版本开始就有这个类或者接口，@deprecated 表示不建议使用该类或者接口。
示例：
/**
* LogManager 类集中控制对日志读写的操作。
* 全部为静态变量和静态方法，对外提供统一接口。分配对应日志类型的读写器，
* 读取或写入符合条件的日志纪录。
* @author 张三，李四，王五
* @version 1.2, 2001-03-25
* @see LogIteraotor
* @see BasicLog
* @since CommonLog1.0
*/
示例：
/**
* 注释内容
*/
private String logType;
/**
* 注释内容
*/
public void write()
格式：
/**
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @param [参数1] [参数1说明]
* @param [参数2] [参数2说明]
* @return [返回类型说明]
* @exception/throws [违例类型] [违例说明]
* @see [类、类#方法、类#成员]
* @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 CommonLog1.0
*/
public static LogIterator read(String logType, Date startTime, Date endTime,
int logLevel, String userName, int bufferNum)
说明：异常注释用@exception或@throws表示，在JavaDoc中两者等价，但推荐用@exception标注Runtime异常，@throws标注非Runtime异常。异常的注释必须说明该异常的含义及什么条件下抛出该异常。
说明：可使程序排版整齐，并方便注释的阅读与理解。
示例：如下例子，排版不整齐，阅读稍感不方便。
public void example( )
{
// 注释
CodeBlock One
// 注释
CodeBlock Two
}
应改为如下布局。
public void example( )
{
// 注释
CodeBlock One
// 注释
CodeBlock Two
}
示例：如下例子，显得代码过于紧凑。
//注释
program code one
//注释
program code two
应如下书写：
//注释
program code one
//注释
program code two
说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。
说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。
说明：错误的注释不但无益反而有害。
说明：在使用缩写时或之前，应对缩写进行必要的说明。
说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。
说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。
说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。
示例：如下注释意义不大。
// 如果 receiveFlag 为真
if (receiveFlag)
而如下的注释则给出了额外有用的信息。
// 如果从连结收到消息
if (receiveFlag)
说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。
示例：参见如下例子。
if (...)
{
program code1
while (index < MAX_INDEX)
{
program code2
} // end of while (index < MAX_INDEX) // 指明该条while语句结束
} // end of if (...) // 指明是哪条if语句结束
说明：注释语言不统一，影响程序易读性和外观排版，出于维护的考虑，建议使用中文。
说明：调试程序的时候可以方便的使用 /* 。。。*/ 注释掉一长段程序。
说明：JavaDoc工具收集简介的时候使用选取第一句话。
示例：如下是对设置属性的流程注释
//1、 判断输入参数是否有效。
。。。。。
// 2、设置本地变量。
。。。。。。
示例：这里主要是对闰年算法的说明。
//1. 如果能被4整除，是闰年；
//2. 如果能被100整除，不是闰年.；
//3. 如果能被400整除，是闰年.。
格式：
com.huawei.产品名.模块名称
com.huawei.部门名称. 项目名称
示例：
Relay模块包名 com.huawei.msg.relay
通用日志模块包名 com.huawei.msg.log
示例：OrderInformation, CustomerList, LogManager, LogConfig
示例：
private void calculateRate();
public void addNewOrder();
格式：
get + 非布尔属性名()
is + 布尔属性名()
set + 属性名()
动词()
动词 + 宾语()
示例：
public String getType();
public boolean isFinished();
public void setVisible(boolean);
public void show();
public void addKeyListener(Listener);
示例：
private customerName;
private orderNumber;
private smpSession;
示例：
public final static int MAX_VALUE = 1000;
public final static String DEFAULT_START_DATE = "2001-12-08";
示例：
public class Person
{
private String name;
private static List properties;
public void setName (String name)
{
this.name = name;
}
public void setProperties (List properties)
{
Person.properties = properties;
}
}
示例：
Application 类型的，命名以App 结尾——MainApp
Frame 类型的，命名以Frame 结尾——TopoFrame
Panel 类型的，建议命名以Panel 结尾——CreateCircuitPanel
Bean 类型的，建议命名以Bean 结尾——DataAccessBean
EJB 类型的，建议命名以EJB 结尾——DBProxyEJB
Applet 类型的，建议命名以Applet 结尾——PictureShowApplet
示例：getCustomerInformation() 改为 getCustomerInfo()
示例：protected void setUserName(), private void calculateRate()
示例：customers, orderItems
说明：虽然为仅用一两行就可完成的功能去编方法好象没有必要，但用方法可使功能明确化，增加程序可读性，亦可方便维护、测试。
说明：对于模块间接口方法的参数的合法性检查这一问题，往往有两个极端现象，即：要么是调用者和被调用者对参数均不作合法性检查，结果就遗漏了合法性检查这一必要的处理过程，造成问题隐患；要么就是调用者和被调用者均对参数进行合法性检查，这种情况虽不会造成问题，但产生了冗余代码，降低了效率。
说明：划分类的时候，应该尽量把逻辑处理、数据和显示分离，实现类功能的单一性。
示例：
数据类不能包含数据处理的逻辑。
通信类不能包含显示处理的逻辑。
说明： 父类如果实现了比较合理的toString() ，子类可以继承不必再重写。
示例：
public TopoNode
{
private String nodeName;
public String toString()
{
return "NodeName : " + nodeName;
}
}
示例：
try
{
// ... ...
}
catch(IOException ioe)
{
//... ...
}
finally
{
try
{
out.close();
}
catch (IOException ioe)
{
//... ...
}
}
说明：若有特殊原因必须用注释加以说明。
示例：
try
{
//.... ...
}
catch (IOException ioe)
{
ioe.printStackTrace ();
}
说明：便于问题定位。
示例：
throw new IOException("Writing data error! Data: " + data.toString());
说明：
非运行期异常是由外界运行环境决定异常抛出条件的异常，例如文件操作，可能受权限、磁盘空间大小的影响而失败，这种异常是程序本身无法避免的，需要调用者明确考虑该异常出现时该如何处理方法，因此非运行期异常必须有throws子句标出，不标出或者调用者不捕获该类型异常都会导致编译失败，从而防止程序员本身疏忽。
运行期异常是程序在运行过程中本身考虑不周导致的异常，例如传入错误的参数等。抛出运行期异常的目的是防止异常扩散，导致定位困难。因此在做异常体系设计时要根据错误的性质合理选择自定义异常的继承关系。
还有一种异常是Error 继承而来的，这种异常由虚拟机自己维护，表示发生了致命错误，程序无法继续运行例如内存不足。我们自己的程序不应该捕获这种异常，并且也不应该创建该种类型的异常。
说明：
一个系统或者模块应该统一规划异常类型和返回码的含义。
但是不能用异常来做一般流程处理的方式，不要过多地使用异常，异常的处理效率比条件分支低，而且异常的跳转流程难以预测。
说明：防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。
示例：
下列语句中的表达式
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）造成了判断条件出错。
示例：如下的程序可读性差。
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
}
说明：使用int index[] 格式使程序的可读性较差
示例：
如下程序可读性差：
public int getIndex()[]
{
....
}
如下程序可读性好：
public int[] getIndex()
{
....
}
说明：代码发布的时候可以统一关闭调试代码，定位问题的时候又可以打开开关。
示例：NullPointException抛出时常常描述为空，这样往往看不出是出了什么错。
说明： 如果程序中需要分类处理，则将异常根据分类组织成继承关系。如果确实有很多异常类型首先考虑用异常描述来区别，throws/exception子句标明的异常最好不要超过三个。
说明：若此段代码各语句之间有实质性关联并且是完成同一件功能的，那么可考虑把此段代码构造成一个新的方法。
说明：主要类包括：
1、能完成独立功能的类，如通讯。
2、具有完整界面的类，如一个对话框、一个窗口、一个帧等。
3、JavaBean 类。
示例：
public static void main(String[] arguments)
{
CreateCircuitDialog circuitDialog1 = new CreateCircuitDialog (null,
"Ciruit", false);
circuitDialog1.setVisible(true);
}
说明：由于集合保存了对象的句柄，虚拟机的垃圾收集器就不会回收。
说明：便于程序阅读和查找。
示例：矩形的长与宽关系较密切，放在一起。
rect.length = 10;
rect.width = 5;
说明：高技巧语句不等于高效率的程序，实际上程序的效率关键在于算法。
继承层次 5层
类的行数 1000行（包含{}）
类的属性 10个
类的方法 20个
类友好方法 10个
类私有方法 15个
类保护方法 10个
类公有方法 10个
类调用方法 20个
方法参数 5个
return语句 1个
方法行数 30行
方法代码 20行
注释比率 30%~50%
类的方法 20个
类友好方法 10个
类私有方法 15个
类保护方法 10个
类公有方法 10个
类调用方法 20个
方法参数 5个
return语句 1个
方法行数 30行
方法代码 20行
注释比率 30%~50%
标签：
原文地址：http://www.cnblogs.com/isonre/p/4719989.html
