短期目标是定期能出一篇简文,希望自己能坚持下去~~~~( ̄_, ̄ )


附上Android君
今天要分享的是关于Android注释系统的一些强大功能!!

实践证明,拥有良好的注释是可持续维护的重要标准

比如你直接查阅Activity.java 的源码,将会看到大量绿色的注释,而且仔细观察除了我们常规的注释外还有一些特定语法的注释。下面贴上一段来自官方的例子:

/** * An activity is a single, focused thing that the user can do.  Almost all * activities interact with the user, so the Activity class takes care of * creating a window for you in which you can place your UI with * {@link #setContentView}.  While activities are often presented to the user * as full-screen windows, they can also be used in other ways: as floating * windows (via a theme with {@link android.R.attr#windowIsFloating} set) * or embedded inside of another activity (using {@link ActivityGroup}). * * There are two methods almost all subclasses of Activity will implement: * * 
    *
  • {@link #onCreate} is where you initialize your activity. Most * importantly, here you will usually call {@link #setContentView(int)} * with a layout resource defining your UI, and using {@link #findViewById} * to retrieve the widgets in that UI that you need to interact with * programmatically. * *
  • {@link #onPause} is where you deal with the user leaving your * activity. Most importantly, any changes made by the user should at this * point be committed (usually to the * {@link android.content.ContentProvider} holding the data). *
*/

上面的注释除了用了javadoc的/** 我是注释 **/,还能看到使用了 {@link #我是一个class }类似格式语法以及HTML标签语法,如果想写出优雅的注释,提升代码的可读性和可维护性,就有必要了解下Android支持的一些注释语法了。我这里整理了一些常用的语法供大家学习参考~~~~


@link语法

适合在你的注释中引用任意一个类、字段或者方法。

在使用上比较简单,直接放上使用代码:

/** * 这里要引用一个类 {@link package.MyClass} 
* 这里要引用一个类里面的子类 {@link package.MyClass.SubClass}
* 这里要引用一个类里面的方法 {@link package.MyClass#method(Context, Object)} // 注意这里()里面的是方法的参数类型,使用不同的参数签名可以来区别不同的重载方法
* 这里要引用一个类李曼的字段 {@link package.MyClass#field} // 这里不区分字段是否是public 或者 static,都可以直接引用
* 这里要引用改类本身的方法或者字段 {@link #method(Context, Object)}和{@link #field} */

使用这个替代注释中直接写上的类名和方法名!!!**这样查看注释能用IDE直接跳转你引用的地方,并且若重构了引用的类、方法或者字段的名称,IDE也会自动替换这个地方的名称~ ** (如果你碰到经历过年代摧残的代码,你一定遇到过注释中注明的代码早已经不见的情况 -_-|||)


@linkplain语法

功能同@link语法,不过可以给显示指定一个别名

用法可以参考@link,这里贴上不同的地方

/** * 这里要引用一个类 {@linkplain package.MyClass 别名} 
*/

IDE显示效果如下

@linkplain语法

点击别名将跳转到代码处,如果要起别名做注释就用@linkplain替代@link


@param语法

适合给方法的参数写说明

贴上代码

/** * 这是方法的说明 * @param param1 这里是参数1的说明 * @param param2 这是是参数2的说明 */void method(int 参数1, int 参数2) { }

IDE显示效果为

@param语法

用这个语法可以简单为方法参数加一些说明,比如说明一些特殊值的传入等~~


@see语法

在注释的末尾添加,适合说明需要参考的地方,一般作为补充说明用

在上面的例子补充注释

/**     * 这是方法的说明     *     * @param 参数1 这里是参数1的说明     * @param 参数2 这是是参数2的说明     *                 * @see #method()     * @see #method(int)     */    void method(int 参数1, int 参数2) {    }    void method() {    }    void method(int 参数1) {    }

在IDE效果如图

@see语法
可以看到底部出现了 See Also:的备注说明,我通常用来补充一些关联的相似的地方,如重载方法,可以参考的继承类等~~~


@deprecated语法

用于表示该方法已废弃

上代码

    /**     * @deprecated 已废弃,建议使用{@link #method(int)} (int)}     */    void method() {    }

这样在代码调用的时候IDE将会给出提示

@deprecated语法

接着童鞋们查看注释时候我们的@link标签就会引导使用者去使用新的方法~~ 是不是很赞呢,妈妈再也担心我用了废弃的代码了。 Android SDK很多老API都会用这个语法做标注的


@exception语法

适合用于说明可能抛出的异常类型,以及在什么情况下抛出异常
放上一段参数校验代码

    /**     * 这是方法说明     * @param age     * @exception IllegalArgumentException 校验参数有问题将抛出,如age < 0     */    void method(int age) {        if (age < 0) {            throw new IllegalArgumentException("age must >= 0!!!");        }        // TODO ...    }

查看IDE注释,如图

exception语法
对于异常部分将有 Throws:引出,完美提示我为何要抛你异常!!!~~~


语法

适合在你的注释中放上一段高亮的代码

比如

/** * 以下是本类方法的执行顺序 * 
 * public class Activity extends ApplicationContext { *     protected void onCreate(Bundle savedInstanceState); * *     protected void onStart(); * *     protected void onRestart(); * *     protected void onResume(); * *     protected void onPause(); * *     protected void onStop(); * *     protected void onDestroy(); * } * 
*/

然后在你查看这段注释时,IDE将会显示成


高亮的代码段


语法

用于注释的换行

在敲注释的时候可能你会碰到用enter键换行无效的情况,这个时候用
在行的尾部就行了:

/** * 第一行
* 第二行
* 最后一行 */

语法

除了HTML本身支持链接到一个特定URL,也能起到跟<@link>语法一样的引用作用。

直接上代码:

/** * 
    *
  • 可以参考这个字段
  • *
  • 参考这个类
  • *
*/

效果如图

语法
通过IDE点击超链接将直接跳转到对应代码位置~~~~适合给引用起别名,也能很好的放在 HTML语法里面


语法

用于给注释加小标题

上代码,这里用的是

/** * 

Class Info

* 我是Class Info内容 *

Usages

* 我是Usages内容 *

Help

* 我是Help内容 */

IDE查看效果如图:

语法

@docRoot语法

这里是直接用Stack Overflow大神的说法

Here @docRoot is used to compose a reference to an html tutorial. In my case @docRoot translates to the following path:
file:/C:/Users//AppData/Local/Android/android-sdk/docs/reference/

贴上Stack Overflow链接, 意思大致是说这里可以引用到本地安装的sdk的docs位置下。通常是用来在注释中引入docs的资源。
这里给上官方的注释:

/** * 

See the Security and Permissions* document for more information on permissions and security in general. */

IDE查看效果为

@docRoot语法

小结

Android自带的注释语法太多,这里只列了一些常用的,欢迎看到的童鞋留言分享好用的注释语法~~~
(写多了br我这里是用br换行的。。。啦啦啦)

Android除了@语法还能支持基本所有的HTML标签,不过只有合理使用才能写出完美注释,减少团队合作的成本,提高代码可读性.

·
·
·
·
·
·
·
·
·

更多相关文章

  1. Android(安卓)模拟器
  2. Android使用Json和ksoap2调用WebService(WCF)
  3. Android开发者证书的创建
  4. android SQLite使用SQLiteOpenHelper类对数据库进行操作
  5. [置顶] android性能测试工具之dumpstate
  6. AsyncTask异步任务学习笔记(一、异步任务加载网络图片(多图))
  7. Android(安卓)判断用户2G/3G/4G移动数据网络
  8. 6、与iOS、Android的交互 实践篇——传递参数
  9. Android(安卓)Log系统详解

随机推荐

  1. android studio生成JKS时候提示:JKS 密钥
  2. android扫描二维码(zxing)附带小例子
  3. Android上实现柱状图表
  4. Android(安卓)OpenGLES2.0(十三)——流畅的
  5. android gravity用法,我老是记不住
  6. 从零开始--系统深入学习android(实践-让我
  7. 包建强的培训课程(9):Android App性能优化
  8. Android(安卓)进阶之了解源码——Activit
  9. Android通过WebView与JS交互的全面方式
  10. Android构建系统和Gradle知识整理