【Android注釋技巧】Android函數上面的注釋你是怎麼寫的？（Eclipse中）

標籤：eclipse   注釋   see   link   android   

前言：你用過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”

如果你有任何問題，歡迎留言告訴我！

著作權聲明：本文為博主原創文章，未經博主允許不得轉載。

【Android注釋技巧】Android函數上面的注釋你是怎麼寫的？（Eclipse中）