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

-Advertisement-

前言：你用過Eclipse快捷鍵 Alt + Shift + J 麽？你看過源碼麽？如果看過，你註意過源碼上面的註釋麽？你知道為什麼看源碼註釋有些標識的參數可以直接點擊跳轉麽？先出個題目，定義一個最簡單的Person類，三個屬性，一個name，一個age，一個性別，一個帶所有屬性參數的構造函數，你

前言：你用過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 自哪個版本開始

@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;     }

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

把滑鼠放在函數名上
這裡寫圖片描述

點擊可以跳轉註釋

這裡寫圖片描述

2015.8.14更新
當希望註釋換行時，可以在新一行註釋前加上<p>（如果不加，就算換行了，滑鼠放在函數上顯示的也是沒有換行，類似html）如圖

加上<p>標簽後

3. 如何修改註釋模板

不繞圈子，直接給出我在用的模板。下載地址
想瞭解更多地搜索關鍵字“Eclipse 註釋模板”，可以自己自定義模板。

這裡寫圖片描述

使用方法：打開Eclipse -> Window -> Preferences -> Java -> Code Style
1.點擊Code Templates -> Import … “MyCodetemplates.xml”
2.點擊Formatter -> Import …”MyFormatter.xml”

問啊-定製化IT教育平臺，牛人一對一服務，有問必答，開發編程社交頭條官方網站：www.wenaaa.com

QQ群290551701 聚集很多互聯網精英，技術總監，架構師，項目經理！開源技術研究，歡迎業內人士，大牛及新手有志於從事IT行業人員進入！

您的分享是我們最大的動力!

-Advertisement-

更多相關文章

android開發我的新浪微博客戶端-載入頁面UI篇(1.1)

本軟體設定用戶第一個接觸到的功能就是頁面載入等待功能，這個功能對使用者來說就是一個持續1、2秒鐘的等待頁面，在用戶等待的同時程式做一些必要的檢查以及數據準備工作，載入頁面分為UI篇和功能篇，從表及里首先是UI的實現，一個軟體除功能之外還得有一個光鮮的外表也是非常重要的，儘管本人設計水平一般但是還是親
Activity按下2次退出

先看下onBackPressed和onKeyDown的區別在Android上有兩種方法來獲取該按鈕的事件 1.直接獲取按鈕按下事件，此方法相容Android 1.0到Android 2.1 也是常規方法，直接重寫Activity的onKeyDown方法即可，代碼如下: @Override publ
Android游戲開發之游戲幀動畫的播放與處理

帶你走進游戲開發的世界之游戲幀動畫的處理<ignore_js_op> 1.幀動畫的原理幀動畫幀動畫顧名思義，一幀一幀播放的動畫就是幀動畫。幀動畫和我們小時候看的動畫片的原理是一樣的，在相同區域快速切換圖片給人們呈現一種視覺的假象感覺像是在播放動畫，其實不過是N張圖片在一幀一幀的切換罷了。如圖所
別說你會AFNetworking3.0/NSURLSession

很多時候，AFNetworking都是目前iOS開發者網路庫中的不二選擇。Github上2W+的star數足見其流行程度。而從iOS7.0開始，蘋果推出了新的網路庫繼承者NSURLSession後，AFNetworking也毫不猶豫地加入了對其的支持。3.0+更加只是提供了NSURLSession的
iOS IM開發準備工作（四）CocoaAsyncSocket的使用

上一篇亂說了一陣socket，這篇要說說怎麼幹活了。畢竟用過的起來才行。我的項目裡面使用的是CocoaAsyncSocket，這個是對CFSocket的封裝。如果你覺得自己可以實現封裝或者直接用原生的，我可以告訴你，很累；關鍵是等你弄出來，項目可能都要交了。這個庫，支持TCP和UDP；有GCD和R
iOS-修改modal出來的控制器的大小

- (void)touchesBegan:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event{ static BOOL showFlag = NO; if (!showFlag) { XZHomeViewController *home =
【Android】不彈root請求框檢測手機是否root

由於項目需要root安裝軟體，並且希望在合適的時候引導用戶去開啟root安裝，故需要檢測手機是否root。最基本的判斷如下，直接運行一個底層命令。(參考https://github.com/Trinea/android-common/blob/master/src/cn/trinea/androi
學習iOS、React Native、演算法開發的建議

我以前寫過不少建議文章，學生時代寫過怎麼學習填鴨，畢業後寫過怎麼學習投資交易，最近寫過怎麼學習iOS開發。寫的這些建議文章都有一個共同的毛病，建議多而全，使得看得人覺得難而累。這次的建議，我儘量寫得簡化一點。 1、iOS開發學習iOS開發把我的工資提升了6倍多。而且，即使提升到16倍，我也不覺得