【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. 如何快速生成文档注释

其实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;
    }
}

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

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

2. 文档注释中字段的含义(重点)

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

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

  • (空)在所有标签上面写的文字将成为描述该函数的关键性文字
  • @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;
    }

把鼠标放在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;
    }

把鼠标放在函数名上

点击可以跳转注释

3. 如何修改注释模板

不绕圈子,直接给出我们公司在用的模板。下载地址

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

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

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

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

如果你有任何问题,欢迎留言告诉我!

版权声明:本文为博主原创文章,未经博主允许不得转载。

时间: 2024-10-07 05:29:43

【Android注释技巧】Android函数上面的注释你是怎么写的?(Eclipse中)的相关文章

Android:在设置Button上面的内容(含字母时)字母被强制转换成了大写

之前Button中的内容一直是中文,今天无意用了英文,偶然发现设置Button上面的内容(含字母时)字母被转换成了大写. 原因有可能是:Android 5.0的sdk在新建项目时的默认主题是android:theme="@style/AppTheme"的关系.当我把主题删掉后,回复正常了. 解决的办法有: 1.修改主题样式 2.在设置Button内容是加上android:textAllCaps="false",使其不会自动转换为大写 默认情况下(字母被转换成了大写)

[Android]通过setImageURI设置网络上面的图片

设置imageView显示网络上的图片 picUrl = new URL(getIntent().getExtras().getString("map_url")); Bitmap pngBM = BitmapFactory.decodeStream(picUrl.openStream()); mapIMG.setImageBitmap(pngBM);

Android 开发技巧 - Android 6.0 以上权限大坑和权限检查基类封装

简单介绍 关于运行时权限的说法,早在Google发布android 6.0的时候,大家也听得蛮多的.从用户的角度来讲,用户是受益方,更好的保护用户的意思,而对于开发者来说,无疑增加了工作量. 对于6.0以下的权限在安装时,会根据权限声明产生一个权限列表,用户只有同意才能完成app的安装.而在6.0以后,不需要先对权限授权就可以安装app,对于权限的授权我们可以选择禁止. 在新的权限机制中,Google将权限分为两类: Normal Permissions(普通权限):不涉及用户隐私,不需要用户进

Android数据库之基本概念(上)

1.Android数据库简介 Android通过结合使用SQLite数据库和Content Provider,提供了结构化数据的持久功能. SQLite数据库可以通过一种结构化的.易于管理的方法来存储应用程序数据.Android提供了一个完整的SQLite关系数据库的库文件.每个应用程序都可以创建自己的数据库,并对这个数据库拥有完全的控制权. Android数据库存储在设备上的/data/data/<package name>/database文件夹中,所有的数据库都是私有的,只能被创建他们的

Android开发学习总结(二)——使用Android Studio搭建Android集成开发环境

有很长一段时间没有更新博客了,最近实在是太忙了,没有时间去总结,现在终于可以有时间去总结一些Android上面的东西了,很久以前写过这篇关于使用Android Studio搭建Android集成开发环境,不过一直没有发表出来,写这篇文章的目的是记录一下Android开发环境的搭建过程,这篇文章写得一般般,主要是记录了整个搭建过程,没什么技术含量,觉得有帮助的朋友就看一下! 一.Android Studio简单介绍 2013年GoogleI/O大会首次发布了Android Studio IDE(A

在Eclipse中搭建cocos2d-x的Android开发环境(免cygwin)

在突击几天学习Android开发之后,我开始转向cocos2d-x的Android开发了.由于自己以前有了解过cocos2d-x的开发,当时自己也学过不少游戏引擎,觉得cocos2d-x作为一个游戏引擎实在是比较简陋,没想到cocos2d-x现在红得发紫,这是我远远没有想到的.于是也赶赶潮流的末班车,查资料顺利地在Eclipse上搭建cocos2d-x的Androd开发环境. 原创文章,反对未声明的引用.原博客地址:http://blog.csdn.net/gamesdev/article/de

在Kotlin中使用注释处理Android框架 kapt

本教程介绍如何在 Kotlin 中使用依赖于注释处理的流行的 Android 框架和库. 在日常 Android 开发中,流行着数以千计的框架帮助我们提升开发效率. 使用 Kotlin 开发时仍然可以沿用这些框架,而且和使用 Java 同样简单. 本章教程将提供相关示例并重点介绍配置的差异. 教程以 Dagger. Butterknife. Data Binding. Auto-parcel 以及 DBFlow 为例(其它框架配置基本类似). 以上框架均基于注解处理方式工作:通过对代码注解自动生

android的布局xml文件如何添加注释?

xml布局文件如图添加注释后报错,错误内容如下: 上网查阅xml添加注释的语法规则: XML 中的注释 在 XML 中编写注释的语法与 HTML 的语法很相似: <!--This is a comment--> 并不是注释本身的问题. 因此可能是Android中的xml有特殊的规定,继续搜索发现有网友说: Android中的xml只能在组件布局代码后,或者在组件的前面添加注释.如下所示:<RelativeLayout        android:id="@+id/item_l

我的Android进阶之旅------&gt;android Button上面的英文字符串自动大写的问题解决

今天碰到一个关于Button的问题:android Button上面的英文字符串会自动变成大写,运行的Android 5.1版本,如下图所示: 图1:Button 图2:TextView 这个Button的定义代码如下 <Button android:id="@+id/addContacts" android:layout_width="match_parent" android:layout_height="wrap_content" a