你的位置:首页 > 操作系统

[操作系统]【Android注释技巧】Android函数上面的注释你是怎么写的?(Eclipse中)


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

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

public class Person {   private String mName;   private int mAge;   private int mSex;   public Person(final String name, final int age, final int sex) {     super();     this.mName = name;     this.mAge = age;     this.mSex = sex;   } }
  • 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… 
    能够快速选择要重写或者要实现的超类的函数;

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

/** * @ClassName Person * @Description 人类 * @author AZZ * @Date 2015年8月6日 下午3:27:39 * @version 1.0.0 */ public class Person {   /**   * @Field @age : 年龄   */   private int mAge;   /**   * @Field @name : 姓名   */   private String mName;   /**   * @Field @sex : 性别   */   private int mSex;   /**   * @Description 构造函数   * @param age 年龄   * @param name 姓名   * @param sex 性别   */   public Person(int age, String name, int sex) {     super();     this.mAge = age;     this.mName = name;     this.mSex = sex;   } }
  • 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 自哪个版本开始

测试代码段

 /**   * 测试方法-测试各个注释标签的显示   * @author 作者信息 - AZZ   * @param param 输入参数   * @return 返回参数   * @throws Exception 参数不合法异常   * @exception IllegalArgumentException param小于0 或者 param大于100   * @category 分类信息   * @since JDK1.0   */   public boolean test(int param) throws Exception {     if (param < 0 || param > 100) {       throw new Exception("wrong param");     }     return false;   }
  • 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?)
  /**   * @Field @MALE : 男性   */   public static int MALE = 0;   /**   * @Field @FEMALE : 女性   */   public static int FEMALE = 1;   /**   * the mSex to set   * @param sex either {@link #FEMALE} or {@link #MALE}    * 测试链接方法 {@link #test(int)}   * 测试链接类 {@link com.test.note.Person}   */   public void setSex(int sex) {     this.mSex = sex;   }
  • 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.2.点击Formatter -> Import …”MyFormatter.

这里写图片描述

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

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