【Android注释技巧】Android函数上面的注释你是怎么写的？（Eclipse中）

前言：你用过Eclipse快捷键 Alt + Shift + J 么？你看过源码么？如果看过，你注意过源码上面的注释么？你知道为什么看源码注释有些标识的参数可以直接点击跳转么？

先出个题目，定义一个最简单的Person类，三个属性，一个name，一个age，一个性别，一个带所有属性参数的构造函数，你会怎么写？

<code class="hljs java has-numbering"><span class="hljs-keyword">public <span class="hljs-class"><span class="hljs-keyword">class <span class="hljs-title">Person {     <span class="hljs-keyword">private String mName;     <span class="hljs-keyword">private <span class="hljs-keyword">int mAge;     <span class="hljs-keyword">private <span class="hljs-keyword">int mSex;      <span class="hljs-keyword">public <span class="hljs-title">Person(<span class="hljs-keyword">final String name, <span class="hljs-keyword">final <span class="hljs-keyword">int age, <span class="hljs-keyword">final <span class="hljs-keyword">int sex) {         <span class="hljs-keyword">super();         <span class="hljs-keyword">this.mName = name;         <span class="hljs-keyword">this.mAge = age;         <span class="hljs-keyword">this.mSex = sex;     } }</span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></code>

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

我相信没有人在做项目时是这么干巴巴地写吧！一点注释都没有！这里例子简单，从属性名就能看出意思，如果换难理解一点的，代码量又增多时，看起来就会很头疼了。

1. 如何快速生成文档注释

其实Eclipse有快速生成文档注释的办法，光标定位到要注释的类、属性或者函数上，然后右键 -> Source -> Generate Element Comment，我更喜欢用快捷键 Alt + Shift + J，就能自动生成注释了！



顺带一提一点基础技巧，图中右侧下面的

Generate Constructor using

Fields…

能快速生成带属性参数的构造函数；（我上文说要生成多参数构造函数就可以这么快速生成）
Generate Getters and Setters…

快速生成属性的获取器和设置器；（这个功能学校老师为了让我们多敲点代码没说，在实习的时候才知道有这功能）
Override / Implement Methods…

能够快速选择要重写或者要实现的超类的函数；

然后自动生成注释后的代码变成了这个样子

<code class="hljs java has-numbering"><span class="hljs-javadoc">/**  *<span class="hljs-javadoctag"> @ClassName Person  *<span class="hljs-javadoctag"> @Description 人类  *<span class="hljs-javadoctag"> @author AZZ  *<span class="hljs-javadoctag"> @Date 2015年8月6日 下午3:27:39  *<span class="hljs-javadoctag"> @version 1.0.0  */ <span class="hljs-keyword">public <span class="hljs-class"><span class="hljs-keyword">class <span class="hljs-title">Person {     <span class="hljs-javadoc">/**      *<span class="hljs-javadoctag"> @Field<span class="hljs-javadoctag"> @age : 年龄      */     <span class="hljs-keyword">private <span class="hljs-keyword">int mAge;     <span class="hljs-javadoc">/**      *<span class="hljs-javadoctag"> @Field<span class="hljs-javadoctag"> @name : 姓名      */     <span class="hljs-keyword">private String mName;     <span class="hljs-javadoc">/**      *<span class="hljs-javadoctag"> @Field<span class="hljs-javadoctag"> @sex : 性别      */     <span class="hljs-keyword">private <span class="hljs-keyword">int mSex;     <span class="hljs-javadoc">/**      *<span class="hljs-javadoctag"> @Description 构造函数      *<span class="hljs-javadoctag"> @param age 年龄      *<span class="hljs-javadoctag"> @param name 姓名      *<span class="hljs-javadoctag"> @param sex 性别      */     <span class="hljs-keyword">public <span class="hljs-title">Person(<span class="hljs-keyword">int age, String name, <span class="hljs-keyword">int sex) {         <span class="hljs-keyword">super();         <span class="hljs-keyword">this.mAge = age;         <span class="hljs-keyword">this.mName = name;         <span class="hljs-keyword">this.mSex = sex;     } }</span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></code>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

虽然代码变长了，但是注释清晰，容易阅读了，最关键的是，文档注释能让你在其他用到该类、该方法、该属性的地方有提示。

你的代码添加注释后也这个样子么？我想应该是不一样的。因为我修改了注释模板！~所以你看到会有一些自定义的标签比如“@ClassName”，“@Description”,“Field”。如果喜欢这个模板可以去看第三点怎么改。

2. 文档注释中字段的含义（重点）

由于后面图片过大，导致看起来不是很简洁，所以先总结一下，有不明白的下面都有截图说明。

（空）在所有标签上面写的文字将成为描述该函数的关键性文字
@author 作者信息
@param 参数信息
@return 返回信息
@exception 异常信息
@throws 抛出异常信息 （@exception 和 @throws 经测试效果是一样的）
@category 分类信息
@since 自哪个版本开始
@see 有的函数需要借助其他类或者函数或者属性，就用该标签标识。

@see #本类函数名/属性名 可以查看其他函数或属性
@see 包名.类名 可以查看其他类

-

@deprecated 表示该函数不建议使用了，在这个标签里写上为什么不建议使用以及提供替换该方法的新方法。加上这个标签后，注释显示里不会提示，但是函数名会被画一道删除线

-
引用到别的参数或者类或者函数。可以这么做：用{@link #函数名/属性名}来链接本类属性/函数，用{@link 包名.类名}来链接其他类

-
2015.8.14更新：当希望注释换行时，可以在新一行注释前加上

<p>

（如果不加，就算换行了，鼠标放在函数上显示的也是没有换行，类似html）

下面正式附图说明：

在文档注释中用一些字段标明信息，能很明确的告诉别人这个函数/类的作用，而且文档注释很棒的一点就是在别的地方调用时把鼠标放在该函数/类上时，能够看到你之前写好的注释。



在文档注释代码段中，默认带有的字段有

（空）在所有标签上面写的文字将成为描述该函数的关键性文字
@author 作者信息
@param 参数信息
@return 返回信息
@exception 异常信息
@throws 抛出异常信息 （@exception 和 @throws 经测试效果是一样的）
@category 分类信息
@since 自哪个版本开始

测试代码段

<code class="hljs java has-numbering"> <span class="hljs-javadoc">/**      * 测试方法-测试各个注释标签的显示      *<span class="hljs-javadoctag"> @author 作者信息 - AZZ      *<span class="hljs-javadoctag"> @param param 输入参数      *<span class="hljs-javadoctag"> @return 返回参数      *<span class="hljs-javadoctag"> @throws Exception 参数不合法异常      *<span class="hljs-javadoctag"> @exception IllegalArgumentException param小于0 或者 param大于100      *<span class="hljs-javadoctag"> @category 分类信息      *<span class="hljs-javadoctag"> @since JDK1.0      */     <span class="hljs-keyword">public <span class="hljs-keyword">boolean <span class="hljs-title">test(<span class="hljs-keyword">int param) <span class="hljs-keyword">throws Exception {         <span class="hljs-keyword">if (param < <span class="hljs-number">0 || param > <span class="hljs-number">100) {             <span class="hljs-keyword">throw <span class="hljs-keyword">new Exception(<span class="hljs-string">"wrong param");         }         <span class="hljs-keyword">return <span class="hljs-keyword">false;     }</span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></code>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

把鼠标放在test上会显示如下



@see 有的函数需要借助其他类或者函数或者属性，就用该标签标识。

@see #本类函数名/属性名 可以查看其他函数或属性
@see 包名.类名 可以查看其他类





点击可以跳转显示相应类/函数/属性注释





@deprecated 表示该函数不建议使用了，在这个标签里写上为什么不建议使用以及提供替换该方法的新方法。加上这个标签后，注释显示里不会提示，但是函数名会被画一道删除线



@自定义标签名 比如@Date @Description等，可以自己自定义一些标签名，这些标签的注释会自动排列到默认标签的下面



另外，在文档注释里面，比如@param 的解释中，有时候我们需要引用到别的参数或者类或者函数。比如，现在在Person类里面定义两个整型常量，标识男女，在

setSex()

函数中，我想提示使用者设置我已经给定的两个常量，可以这么做：用{@link #函数名/属性名}来链接本类属性/函数，用{@link 包名.类名}来链接其他类（是不是想到了@see?）

<code class="hljs java has-numbering">    <span class="hljs-javadoc">/**      *<span class="hljs-javadoctag"> @Field<span class="hljs-javadoctag"> @MALE : 男性      */     <span class="hljs-keyword">public <span class="hljs-keyword">static <span class="hljs-keyword">int MALE = <span class="hljs-number">0;     <span class="hljs-javadoc">/**      *<span class="hljs-javadoctag"> @Field<span class="hljs-javadoctag"> @FEMALE : 女性      */     <span class="hljs-keyword">public <span class="hljs-keyword">static <span class="hljs-keyword">int FEMALE = <span class="hljs-number">1;      <span class="hljs-javadoc">/**      * the mSex to set      *<span class="hljs-javadoctag"> @param sex  either {@link #FEMALE} or {@link #MALE}       * 测试链接方法 {@link #test(int)}      * 测试链接类 {@link com.test.note.Person}      */     <span class="hljs-keyword">public <span class="hljs-keyword">void <span class="hljs-title">setSex(<span class="hljs-keyword">int sex) {         <span class="hljs-keyword">this.mSex = sex;     }</span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></span></code>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

把鼠标放在函数名上



点击可以跳转注释



2015.8.14更新

当希望注释换行时，可以在新一行注释前加上

<p>

（如果不加，就算换行了，鼠标放在函数上显示的也是没有换行，类似html）如图



加上

<p>

标签后

3. 如何修改注释模板

不绕圈子，直接给出我在用的模板。下载地址

想了解更多地搜索关键字“Eclipse 注释模板”，可以自己自定义模板。



使用方法：打开Eclipse -> Window -> Preferences -> Java -> Code Style

1.点击Code Templates -> Import … “MyCodetemplates.xml”

2.点击Formatter -> Import …”MyFormatter.xml”

问啊-定制化IT教育平台，牛人一对一服务，有问必答，开发编程社交头条 官方网站：www.wenaaa.com

QQ群290551701 聚集很多互联网精英，技术总监，架构师，项目经理！开源技术研究，欢迎业内人士，大牛及新手有志于从事IT行业人员进入！