Java 注释规范

注释规范

一、配置文件注释
1、Properties资源文件
文件头注释，要包含作者信息

1 2 3 4 5

########################### ###配置文件描述：内容描述 ###作者：XXX ###创建时间：2010-01-01 ###########################

文件内容分组注释

1 2 3 4 5 6 7 8 9 10

###类别管理start### ###零部件类别### Category.0=0,零件类别 ###材料费分类### Category.1=1,材料费分类 ###任务类别### Category.2=2,任务类别 ###分厂类别### Category.3=3,分厂类别 ###类别管理end###

其中的KEY值和Value值必须一一对应。不要出现空值的现象
每增加一行都应该有一个注释，由三个#开头和结尾
2、Xml配置文件
文件头注释，要包含作者信息，放在字符集声明的后面

1 2	<?xml version="1.0" encoding="UTF-8" ?> <!-- /*  * 配置文件描述：内容描述  * 作者：XXX  * 创建时间：2010-01-01  */ -->

二、Java文件注释
1、文件注释(Files)

1 2 3 4 5 6 7 8 9 10 11

/**  * @Project: ${project_name}  * @Title: ${type_name}  * @Package ${package_name}  * @Description: ${todo}  * @Company: 乐购科技信息技术有限公司  * @author ${user} ${user}@itblood.com  * @date ${date} ${time}  * @Copyright： ${year}  * @version V1.0 */

2、类注释(Types)

1 2 3 4 5 6 7

/**  * @ClassName: ${type_name}  * @Description: ${todo} (请用一句话描述该类做什么)  * @author ${user} ${user}@itblood.com  * @date: ${date} ${time}  * ${tags} */

3、方法注释

1 2 3 4 5 6 7 8

/**  * @Title: ${enclosing_method}  * @Description: ${todo}  * @author: ${user} ${user}@itblood.com  * @date: ${date} ${time}  * @return ${return_type}  * @throws */

4、方法修改注释
自己在修改别人的代码时，需要注释；
虽然是自己的代码，但出现了大的业务改动，需要注释
修改方法：
1) 对于在类中增加或删除方法，需要在类注释中记录变更信息
2) 对于类的方法的修改，需要在方法注释中记录变更信息
3) 在注释中的author一栏中加入修改人、修改时间和修改原因及主要内容

1 2 3 4 5 6 7 8 9 10 11 12

/**  * @Title: ${enclosing_method}  * @Description: ${todo}  * @author: ${user} ${user}@itblood.com  * @date: ${date} ${time}  * @param ${tags}  * @return ${return_type}  * @throws  * @modified by ${user} ${user}@itblood.com  * @modified date ${date} ${time}  * @@modified description ${todo} */

5、类成员变量
类成员变量及常量使用以下方式进行注释，该注释信息体现在javadoc自动生成文档中
1) 注释需要写在对应代码的上方，之间不允许空行
2) 如果注释在一行内，采用这样的注释

1	/** 变量的说明 */

3) 如果注释在多行内，采用这样的注释

1 2 3 4

/** * 变量的说明 * */

6、方法成员变量
类方法中的局部变量注释方式如下，该注释信息不体现在javadoc生成文档中
1) 注释需要写在对应代码的上方，之间不允许空行
2) 如果注释在一行内，采用这样的注释

1	/* 变量的说明 */ 或者 //变量的说明

3) 如果注释在多行内，采用这样的注释

1 2 3 4

/*  * 变量的说明  * */

三、Jsp文件注释
应该在JSP文件中字符集声明的后面，应遵守这样的规范，此方式注释JSP引擎会自动忽略，不会被发送到客户端

四、Javascript注释
1、头部注释

1 2 3 4 5 6 7

/**  * @Description: ${todo}  * @Company: 乐购科技信息技术有限公司  * @author ${user} ${user}@itblood.com  * @date ${date} ${time}  * @version V1.0 */

2、内容注释
每个变量的声明语句单独放到一行,并加上注释说明。每行缩进要保持一致

1 2	var currentEntry; // 注释内容 var size;          //注释内容

单行注释与多行注释

1 2 3 4

// 注释内容 /* 注释内容 */