【Android註釋技巧】Android函數上面的註釋你是怎麼寫的?(Eclipse中)

来源:http://www.cnblogs.com/8hao/archive/2016/03/02/5235368.html
-Advertisement-
Play Games

前言:你用過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
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12

我相信沒有人在做項目時是這麼乾巴巴地寫吧!一點註釋都沒有!這裡例子簡單,從屬性名就能看出意思,如果換難理解一點的,代碼量又增多時,看起來就會很頭疼了。

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;     } }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33

雖然代碼變長了,但是註釋清晰,容易閱讀了,最關鍵的是,文檔註釋能讓你在其他用到該類、該方法、該屬性的地方有提示。 
你的代碼添加註釋後也這個樣子麽?我想應該是不一樣的。因為我修改了註釋模板!~所以你看到會有一些自定義的標簽比如“@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;     }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16

把滑鼠放在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;     }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18

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

點擊可以跳轉註釋

這裡寫圖片描述

  • 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-
Play Games
更多相關文章
  • 本軟體設定用戶第一個接觸到的功能就是頁面載入等待功能,這個功能對使用者來說就是一個持續1、2秒鐘的等待頁面,在用戶等待的同時程式做一些必要的檢查以及數據準備工作,載入頁面分為UI篇和功能篇,從表及里首先是UI的實現,一個軟體除功能之外還得有一個光鮮的外表也是非常重要的,儘管本人設計水平一般但是還是親
  • 先看下onBackPressed和onKeyDown的區別 在Android上有兩種方法來獲取該按鈕的事件 1.直接獲取按鈕按下事件,此方法相容Android 1.0到Android 2.1 也是常規方法,直接重寫Activity的onKeyDown方法即可,代碼如下: @Override publ
  • 帶你走進游戲開發的世界之游戲幀動畫的處理<ignore_js_op> 1.幀動畫的原理 幀動畫幀動畫顧名思義,一幀一幀播放的動畫就是幀動畫。 幀動畫和我們小時候看的動畫片的原理是一樣的,在相同區域快速切換圖片給人們呈現一種視覺的假象感覺像是在播放動畫,其實不過是N張圖片在一幀一幀的切換罷了。 如圖所
  • 很多時候,AFNetworking都是目前iOS開發者網路庫中的不二選擇。Github上2W+的star數足見其流行程度。而從iOS7.0開始,蘋果推出了新的網路庫繼承者NSURLSession後,AFNetworking也毫不猶豫地加入了對其的支持。3.0+更加只是提供了NSURLSession的
  • 上一篇亂說了一陣socket,這篇要說說怎麼幹活了。畢竟用過的起來才行。 我的項目裡面使用的是CocoaAsyncSocket,這個是對CFSocket的封裝。如果你覺得自己可以實現封裝或者直接用原生的,我可以告訴你,很累;關鍵是等你弄出來,項目可能都要交了。這個庫,支持TCP和UDP;有GCD和R
  • - (void)touchesBegan:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event{ static BOOL showFlag = NO; if (!showFlag) { XZHomeViewController *home =
  • 由於項目需要root安裝軟體,並且希望在合適的時候引導用戶去開啟root安裝,故需要檢測手機是否root。 最基本的判斷如下,直接運行一個底層命令。(參考https://github.com/Trinea/android-common/blob/master/src/cn/trinea/androi
  • 我以前寫過不少建議文章,學生時代寫過怎麼學習填鴨,畢業後寫過怎麼學習投資交易,最近寫過怎麼學習iOS開發。 寫的這些建議文章都有一個共同的毛病,建議多而全,使得看得人覺得難而累。 這次的建議,我儘量寫得簡化一點。 1、iOS開發學習iOS開發把我的工資提升了6倍多。而且,即使提升到16倍,我也不覺得
一周排行
    -Advertisement-
    Play Games
  • 一:背景 準備開個系列來聊一下 PerfView 這款工具,熟悉我的朋友都知道我喜歡用 WinDbg,這東西雖然很牛,但也不是萬能的,也有一些場景他解決不了或者很難解決,這時候藉助一些其他的工具來輔助,是一個很不錯的主意。 很多朋友喜歡在項目中以記錄日誌的方式來監控項目的流轉情況,其實 CoreCL ...
  • 本來閑來無事,準備看看Dapper擴展的源碼學習學習其中的編程思想,同時整理一下自己代碼的單元測試,為以後的進一步改進打下基礎。 突然就發現問題了,源碼也不看了,開始改代碼,改了好久。 測試Dapper.LiteSql數據批量插入的時候,耗時20秒,感覺不正常,於是我測試了非Dapper版的Lite ...
  • 需求如下,在DEV框架項目中,需要在表格中增加一列顯示圖片,並且能編輯該列圖片,然後進行保存等操作,最終效果如下 這裡使用的是PictureEdit控制項來實現,打開DEV GridControl設計器,在ColumnEdit選擇PictureEdit: 綁定圖片代碼如下: DataTable dtO ...
  • 前兩天微軟偷偷更新了Visual Studio 2022 正式版版本 17.3 發佈,發佈摘要: MAUI 工作負荷 GA 生成 MAUI/Blazor CSS 熱重載支持 現在,你將能夠使用我們的新增功能在 Visual Studio 中使用每個更新試用一系列新功能。 選擇每個功能以瞭解有關特定功 ...
  • 航天和軍工領域的數字化轉型和建設正在積極推進,在與航天二院、航天三院、航天六院、航天九院、無線電廠、兵工廠等單位交流的過程中,用戶更聚焦試驗和生產過程中的痛點,迫切需要解決軟體平臺統一監測和控制設備及軟體與設備協同的問題。 ...
  • .NET 項目預設情況下 日誌是使用的 ILogger 介面,預設提供一下四種日誌記錄程式: 控制台 調試 EventSource EventLog 這四種記錄程式都是預設包含在 .NET 運行時庫中。關於這四種記錄程式的詳細介紹可以直接查看微軟的官方文檔 https://docs.microsof ...
  • 一:背景 上一篇我們聊到瞭如何去找 熱點函數,這一篇我們來看下當你的程式出現了 非托管記憶體泄漏 時如何去尋找可疑的代碼源頭,其實思路很簡單,就是在 HeapAlloc 或者 VirtualAlloc 時做 Hook 攔截,記錄它的調用棧以及分配的記憶體量, PerfView 會將這個 分配量 做成一個 ...
  • 背景 在 CI/CD 流程當中,測試是 CI 中很重要的部分。跟開發人員關係最大的就是單元測試,單元測試編寫完成之後,我們可以使用 IDE 或者 dot cover 等工具獲得單元測試對於業務代碼的覆蓋率。不過我們需要一個獨立的 CLI 工具,這樣我們才能夠在 Jenkins 的 CI 流程集成。 ...
  • 一、應用場景 大家在使用Mybatis進行開發的時候,經常會遇到一種情況:按照月份month將數據放在不同的表裡面,查詢數據的時候需要跟不同的月份month去查詢不同的表。 但是我們都知道,Mybatis是ORM持久層框架,即:實體關係映射,實體Object與資料庫表之間是存在一一對應的映射關係。比 ...
  • 我國目前並未出台專門針對網路爬蟲技術的法律規範,但在司法實踐中,相關判決已屢見不鮮,K 哥特設了“K哥爬蟲普法”專欄,本欄目通過對真實案例的分析,旨在提高廣大爬蟲工程師的法律意識,知曉如何合法合規利用爬蟲技術,警鐘長鳴,做一個守法、護法、有原則的技術人員。 案情介紹 深圳市快鴿互聯網科技有限公司 2 ...