java 注释模版那些事儿

今天是3.8 妇女节。在这举国欢庆的时刻祝天下女人们节日快乐，尤其从事咱们it行业的女程们，这个节日更应该好好休息享受，感受一下节日的欢乐。一入it深似海...今天正好周六，不知各位男程们在工作岗位上加班的可多呢，辛苦辛苦！外面空气似乎不太好，雾霾大有卷土重来之势，这个情况可比韩剧还虐心，哎！废话少说，下面进入正题，今天想讨论的是关于eclipse 中如何设定代码注释模版。
有过开发经验的朋友们，不管是大公司还是小公司，应该对于代码注释都是很重视的，当然这跟每个公司是否重视代码质量有关。一般来说，每个公司甚至每个项目组都会有自己的一套注释模版，用来做代码整体的规范约束，你说底层的码农们每天的工作成果不就是那一行行的code，对吧。在eclipse这样的开发利器帮助下，可以使用IDE来帮助进行代码注释，提升工作效率。
简单的说一下，代码注释会用到的地方有如下几处：新建类，字段，方法...等等。以eclipse为例，使用注释模版有两种方式：第一种是自己新建注释模板的xml文件，第二种在myEclipse中自己编辑，其原理都是一样的。在此不再赘述。下面以xml格式化配置文档作为例子，详细说明一下具体配置。完整的xml见附件。
[b]1.构造方法[/b]

<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">

/**    
 * 创建一个新的实例 ${enclosing_type}.    
 *    
 * ${tags}    
 */</template>

实例：

/**    
	 * 创建一个新的实例 Person.    
	 *    
	 * @param name
	 * @param age    
	 */
	public Person(String name, int age) {
		super();
		this.name = name;
		this.age = age;
	}

[b]2.非重载方法[/b]

<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">

/**    
 * ${enclosing_method}(这里用一句话描述这个方法的作用)    
 * (这里描述这个方法适用条件 – 可选)    
 * (这里描述这个方法的执行流程 – 可选)    
 * (这里描述这个方法的使用方法 – 可选)    
 * (这里描述这个方法的注意事项 – 可选)    
 * ${tags}    
 * @since  CodingExample　Ver(编码范例查看) 1.1    
 */</template>

实例：

/**
	 * 
	 * sayHi(这里用一句话描述这个方法的作用)    
	 * (这里描述这个方法适用条件 – 可选)    
	 * (这里描述这个方法的执行流程 – 可选)    
	 * (这里描述这个方法的使用方法 – 可选)    
	 * (这里描述这个方法的注意事项 – 可选)    
	 * @param name
	 * @return
	 * @throws Exception    
	 * @since  CodingExample　Ver(编码范例查看) 1.1
	 */
	public String sayHi(String name) throws Exception{
		return null;
	}

[b]3.版本消息[/b]

<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">/**
 * 文件名：${package_name}.${file_name}    
 *    
 * 版本信息：    
 * 日期：${date} ${time}    
 * Copyright @湖南新晃侗族自治县农夫 Corporation ${year}     
 * 版权所有
 */</template>

实例：

/**
 * 文件名：yl.yelang.Person.java    
 *    
 * 版本信息：    
 * 日期：Mar 8, 2014 11:34:50 AM    
 * Copyright @湖南新晃侗族自治县农夫 Corporation 2014     
 * 版权所有
 */
package yl.yelang;

[b]4 类、接口[/b]

<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">/**    
 * 项目名称：${project_name}    
 * 类名称：${type_name}    
 * 类描述：
 * 创建人：农夫    
 * 创建时间：${date} ${time}    
 * 修改人：${user}    
 * 修改时间：${date} ${time}    
 * 修改备注：    
 * @version  Ver 1.0    
 */</template>

实例：

/**    
 * 项目名称：MyEclipseGen    
 * 类名称：Person    
 * 类描述：
 * 创建人：农夫    
 * 创建时间：Mar 8, 2014 11:34:50 AM    
 * 修改人：Administrator    
 * 修改时间：Mar 8, 2014 11:34:50 AM    
 * 修改备注：    
 * @version  Ver 1.0    
 */
public class Person

上述是比较常用的注释模板，其他的比如set/get方法，重载方法，代理方法，字段等如何配置，可以参考副附件中的xml配置。
[b]附录：Eclipse针对java代码模板的内置变量[/b]
注释模板中部分参数详解：
cursor 将编辑器的光标放在这个位置。 N/A

date 插入当前日期。

dollar 插入货币的文字符号。 $

elemType 尝试猜测具有给定 ID 的这个元素的类型。 MyType

enclosing_method 插入模板被插入其中的那个方法的名称。 method()

enclosing_method_arguments 为包围方法插入参数。 arg1, arg2

enclosing_package 插入当前类的包名。 com.example.ui

enclosing_project 插入包含所编辑的这个类的项目的名称。 myProject

enclosing_type 插入正在编辑的类型（类）的名称。 MyType

exception_variable_name 插入一个异常变量名称，进行最佳猜测。 e, ioe

file 文件的简称。 MyType.java
import 如果尚未导入，那么针对给定类型插入一个导入声明。 import com.example.ui.MyOtherType

importStatic 与 import 相同，只不过是静态导入。 import static com.example.ui.MyOtherType.*

line_selection 将选中的行插入到这里。这对用模板包装行是很有用的。 以选中行作为主体的 do、while 循环

primary_type_name 没有扩展名的文件简称。 MyType
time 插入当前的时间。

todo 注释中的 TODO 标记。 TODO

user 当前用户的名字。 ngood

var 解析为本地变量，如果不只一个，就提供一个列表。 myvar

word_selection 插入当前选中的单词。 N/A

year 将现在的年份插入到代码中。 2010
说明，上述变量说明摘自：[url]http://shareal.blog.163.com/blog/static/27659056201193063914196/[/url]。
以上就是eclipse中注释模板的配置，记录下来备忘。另外关于如何在eclipse中编辑注释模版，各位朋友可以自己操作，主要参数跟上述的类同。