Java基础学习总结（36）——Java注释模板

代码注释是对代码设计者、代码阅读者以及系统间调用提供了有效的帮助，最大限度的提高团队开发合作效率增强系统的可维护性。我们追求简化，不是为了写注释而写注释。

（快速使用请直接看六、七、八）

一、原则：

1.注释形式统一

使用统一的注释风格，不要随意创建新的注释风格。

2.注释准确简洁

内容要简单、明了，防止注释的多义性，错误的注释不但无益反而有害。

二、注释条件：

1.基本注释（必须加）

a)类（接口）的注释

b)构造函数的注释

c)方法的注释

d)全局变量的注释

e)字段/属性的注释

注:Bean对象的getter、setter方法不需加注释。

2.局部注释（必须加）

a)典型算法必须有注释。

b)在代码不明晰处必须有注释。

c)在代码修改处加上修改标识的注释。

d)在循环和逻辑分支组成的代码中加注释。

e)为他人提供的接口必须加详细注释。

三、注释格式：

1.单行(single-line)注释：“//……”

2.块(block)注释：“/*……*/”

3.文档注释：“/**……*/”

四、javadoc 注释标签语法

@author对类的说明标明开发该类模块的作者

@version对类的说明标明该类模块的版本

@see对类、属性、方法的说明参考转向，也就是相关主题

@param对方法的说明对方法中某参数的说明

@return对方法的说明对方法返回值的说明

@exception对方法的说明对方法可能抛出的异常进行说明

五、注释：

1.类（接口）注释

/**

* @ClassName: Test

* @Description:TODO(这里用一句话描述这个类的作用)

* @authorjarek

日下午2:25:41

* @Copyright ? 2015上海通善互联网金融信息服务有限公司

*/

publicclass Testextends TextMessageSender {

.....

}

2.构造方法注释

/**

* (这里用一句话描述这个构造函数的作用)

*

*/

public Test() {

super();

// TODO Auto-generated constructor stub

}

/**

* (这里用一句话描述这个构造函数的作用)

*

* @param userId

* @param userName

*/

public Test(StringuserId, String
userName) {

super();

this.userId =userId;

this.userName =userName;

}

3.方法注释

/**

* @method checkUser(这里用一句话描述这个方法的作用)

* @return boolean

* @authorjarek

日下午3:26:33

*/

publicboolean checkUser(StringuserId)
throws Exception {

returntrue;

}

4.全局变量注释

/** 公司代码 */

privatefinal Stringcompay =
"ts";

5.字段/属性注释

// 用户ID

private StringuserId;

// 用户名称

private StringuserName;

6.局部注释

publicstaticvoidensureQueueExists(SQSConnectionconnection, String
queueName)throwsJMSException {

AmazonSQSMessagingClientWrapper
client = connection.getWrappedAmazonSQSClient();

/**

* 检测队列是否存在，不存在则创建

*/

if( !client.queueExists(queueName) ) {

client.createQueue(queueName );

}

}

......

｝

六、代码修改注释

注释格式如下：

修改人，修改时间，UC编码，迭代编码修改说明（原因、内容）可以单行简短注释

如：

日上午11:36:18
@UC_XXXX @In 变更说明（原因、修改内容）

代码改动量小时，在修改代码行前追加注释

对于改动量大时，可以在方法前追加注释

对整个java类变化大时，可以重新追加类注释

七、导入模版(模版文件见文档附件)

<?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="false" context="methodcomment_context" deleted="false" description="Comment for non-overriding methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.methodcomment"
name="methodcomment">/**@method ${enclosing_method}(这里用一句话描述这个方法的作用)

 * @return ${return_type}

 * @author ${user}

 * @date ${date} ${time}

*/</template><template autoinsert="false" context="typecomment_context" deleted="false" description="Comment for created types" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.typecomment" name="typecomment">/**@ClassName: ${type_name}

 * @Description: TODO(这里用一句话描述这个类的作用)

 * @author ${user}

 * @date ${date} ${time}

 * @Copyright © ${year}上海通善互联网金融信息服务有限公司

 */</template><template autoinsert="false" context="constructorcomment_context" deleted="false" description="Comment for created constructors" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.constructorcomment" name="constructorcomment">/**(这里用一句话描述这个构造函数的作用)

 * ${tags}

 */</template><template autoinsert="false" context="gettercomment_context" deleted="false" description="Comment for getter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.gettercomment" name="gettercomment">/**

 * ${bare_field_name}

 *

 * @return  the ${bare_field_name}

 * @since   1.0.0

*/

</template><template autoinsert="true" context="delegatecomment_context" deleted="false" description="Comment for delegate methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.delegatecomment" name="delegatecomment">/**

 * ${tags}

 * ${see_to_target}

 */</template><template autoinsert="false" context="overridecomment_context" deleted="false" description="Comment for overriding methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.overridecomment" name="overridecomment">/** (这里用一句话描述这个方法的作用)

 * ${see_to_overridden}

 */</template><template autoinsert="false" context="fieldcomment_context" deleted="false" description="Comment for fields" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.fieldcomment" name="fieldcomment">/**

 * ${field}:${todo}（用一句话描述这个变量表示什么）

 *

 * @since 1.0.0

 */

</template><template autoinsert="false" context="filecomment_context" deleted="false" description="Comment for created Java files" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.filecomment" name="filecomment"/><template autoinsert="true" context="settercomment_context"
deleted="false" description="Comment for setter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.settercomment" name="settercomment">/**

 * @param ${param} the ${bare_field_name} to set

 */</template></templates>

<?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="true" context="java" deleted="false" description="代码变更注释模版" enabled="true" name="mc">//${user} ${date} ${time}  @UC_XXXX @In 变更说明（原因、修改内容）</template></templates>

八、使用：

只要导入在eclips中导入注释模版即可

通过 /** +回车或 mc +alt+/ 会调出所有模版，提供方便快速注释的功能。