编码规范以及注释规范
文章来源：公众号-智能化IT系统。
编码规范
1.明确方法功能，精确（而不是近似）地实现方法设计。如果一个功能将在多处实现，即使只有两行代码，也应该编写方法实现。
说明：
虽然为仅用一两行就可完成的功能去编方法好象没有必要，但用方法可使功能明确化，增加程序可读性，亦可方便维护、测试。
2.应明确规定对接口方法参数的合法性检查应由方法的调用者负责还是由接口方法本身负责，缺省是由方法调用者负责。
说明：
对于模块间接口方法的参数的合法性检查这一问题，往往有两个极端现象，即：要么是调用者和被调用者对参数均不作合法性检查，结果就遗漏了合法性检查这一必要的处理过程，造成问题隐患；要么就是调用者和被调用者均对参数进行合法性检查，这种情况虽不会造成问题，但产生了冗余代码，降低了效率。
3.明确类的功能，精确（而不是近似）地实现类的设计。一个类仅实现一组相近的功能。说明：划分类的时候，应该尽量把逻辑处理、数据和显示分离，实现类功能的单一性。
示例：
数据类不能包含数据处理的逻辑。通信类不能包含显示处理的逻辑。
4.所有的数据类必须重载toString() 方法，返回该类有意义的内容。说明：父类如果实现了比较合理的toString() ， 子类可以继承不必再重写。
示例：
public TopoNode
{
private String nodeName;
public String toString()
{
return "NodeName : " + nodeName;
}
}
5.数据库操作、IO操作等需要使用结束close()的对象必须在try -catch-finally 的finally中close()。
6.异常捕获后，如果不对该异常进行处理，则应该记录日志（针对后台）。
说明：若有特殊原因必须用注释加以说明。
7.自己抛出的异常必须要填写详细的描述信息。
说明：便于问题定位。
示例：
throw new IOException("Writing data error! Data: " + data.toString());
8. 在程序中使用异常处理还是使用错误返回码处理，根据是否有利于程序结构来确定，并且异常和错误码不应该混合使用，推荐使用异常。说明：一个系统或者模块应该统一规划异常类型和返回码的含义。但是不能用异常来做一般流程处理的方式，不要过多地使用异常，异常的处理效率比条件分支低，而且异常的跳转流程难以预测。
9.避免使用不易理解的数字，用有意义的标识来替代。涉及物理状态或者含有物理意义的常量，不应直接使用数字，必须用有意义的静态变量来代替。
示例：
如下的程序可读性差
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}
10.数组声明的时候使用 int[] index ，而不要使用 int index[] 。说明：
11.异常捕获尽量不要直接 catch (Exception ex) ，应该把异常细分处理。
12.不要使用难懂的技巧性很高的语句，除非很有必要时。说明：高技巧语句不等于高效率的程序，实际上程序的效率关键在于算法。
注释规范
1.在有处理逻辑的代码中，源程序有效注释量必须在20％以上。
说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。
2.文件注释：文件注释写入文件头部。
说明：以/* 开始
示例：
/ *
* 文件名：[文件名]
* 作者：〈版权〉
* 描述：〈描述〉
* 修改人：〈修改人〉
* 修改时间：YYYY-MM-DD
* 修改内容：〈修改内容〉
*/
说明：每次修改后在文件头部写明修改信息。
示例：
/ *
* 文件名：LogManager.java
* 版权：Copyright 2000-2001 Huawei Tech. Co. Ltd. All Rights Reserved.
* 描述： WIN V200R002 WEBSMAP 通用日志系统
* 修改人：张三
* 修改时间：2001-02-16
* 修改内容：新增
* 修改人：李四
* 修改时间：2001-02-26
* 修改内容：。。。。。。
* 修改人：王五
* 修改时间：2001-03-25
* 修改内容：。。。。。。
*/
3.类和接口的注释：该注释放在class定义之前，using或package关键字之后。
示例：
package com. websmap.comm;
/**
* 注释内容
*/
public class CommManager
4.类和接口的注释内容：类的注释主要是一句话功能简述、功能详细描述，说明：可根据需要列出：版本号、生成日期、作者、内容、功能、与其它类的关系等。
格式：
/ *
* 〈一句话功能简述〉
* 〈功能详细描述〉
* @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
*/
5.类属性、公有和保护方法注释：写在类属性、公有和保护方法上面。用//来注释,需要对齐被注释代码。
示例：
/ /注释内容
private String logType
6.成员变量注释内容：成员变量的意义、目的、功能，可能被用到的地方。用//来注释,需要对齐被注释代码
7.公有和保护方法注释内容：列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。
格式：
/ **
*〈一句话功能简述〉
*〈功能详细描述〉
* @param [参数1] [参数1说明]
* @param [参数2] [参数2说明]
* @return [返回类型说明]
* @exception/throws [违例类型] [违例说明]
* @see [类、类#方法、类#成员]
* @deprecated
*/
说明：@since 表示从那个版本开始就有这个方法；@exception或throws 列出可能出现的异常；@deprecated 表示不建议使用该方法。
8.对于方法内部用throw语句抛出的异常，必须在方法的注释中标明，对于所调用的其他方法所抛出的异常，选择主要的在注释中说明。对于非RuntimeException ，即throws子句声明会抛出的异常，必须在方法的注释中标明。
说明：
异常注释用@exception或@throws表示，在JavaDoc中两者等价，但推荐用@exception标注Runtime 异常，@throws标注非Runtime 异常。异常的注释必须说明该异常的含义及什么条件下抛出该异常。
9.注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。
10.注释的排版，按照上述示例来展示。
11.注释应该放在被注释的代码前面，分行展示，但中间不留空行。
12.对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。
说明：分支语句往往是程序实现某一特定功能的关键。
13.边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。
14.注释的内容要清楚、明了，含义准确，防止注释二义性。说明：错误的注释不但无益反而有害。
15.避免在注释中使用缩写，特别是不常用缩写。说明：在使用缩写时或之前，应对缩写进行必要的说明。
公众号-智能化IT系统。每周都有技术文章推送，包括原创技术干货，以及技术工作的心得分享。扫描下方关注。
