编写优美Android注释的常用语法

编写优美Android注释的常用语法

 

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

---

 

附上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:
 *
 * <ul>
 *     <li> {@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.
 *
 *     <li> {@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).
 * </ul>
 */

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

---

@link语法

适合在你的注释中引用任意一个类、字段或者方法。<br />
在使用上比较简单，直接放上使用代码：

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

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

---

@linkplain语法

功能同@link语法，不过可以给显示指定一个别名<br />
用法可以参考@link，这里贴上不同的地方

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

IDE显示效果如下

 

@linkplain语法

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

---

@param语法

适合给方法的参数写说明<br />
贴上代码

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

IDE显示效果为

 

@param语法

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

---

@see语法

在注释的末尾添加，适合说明需要参考的地方，一般作为补充说明用<br />
在上面的例子补充注释

/**
     * 这是方法的说明
     *
     * @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语法

用于表示该方法已废弃<br />
上代码

    /**
     * @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:引出，完美提示我为何要抛你异常！！！~~~

---

<pre class="prettyprint">语法

适合在你的注释中放上一段高亮的代码<br />
比如

/**
 * 以下是本类方法的执行顺序
 * <pre class="prettyprint">
 * 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();
 * }
 * </pre>
 */

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

 

高亮的代码段

---

语法

用于注释的换行<br />
在敲注释的时候可能你会碰到用enter键换行无效的情况，这个时候用
在行的尾部就行了：

/**
 * 第一行<br />
 * 第二行<br />
 * 最后一行
 */

---

<a/>语法

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

直接上代码：

/**
 * <ul>
 *     <li><a href="#FROM_WHERE_SHOW_TEAM">可以参考这个字段</a></li>
 *     <li><a href="package.MyClass">参考这个类</a></li>
 * </ul>
 */

效果如图

 

<a/>语法

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

---

<h/>语法

用于给注释加小标题<br />
上代码,这里用的是<h3/>

/**
 * <h3>Class Info</h3>
 *  我是Class Info内容
 * <h3>Usages</h3>
 *  我是Usages内容
 * <h3>Help</h3>
 *  我是Help内容
 */

IDE查看效果如图：

 

<h/>语法

---

@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/<username>/AppData/Local/Android/android-sdk/docs/reference/

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

/**
 * <p>See the <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>* document for more information on permissions and security in general.
 */

IDE查看效果为

 

@docRoot语法

---

小结

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

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