Java 注釋 Java 注釋

标簽 : Java基礎

五月份得知入職阿裡雲OS, 才開始學Java, 斷斷續續學習/使用半年, 越來越喜歡這個語言/工具. 後來被擁抱變化之後, 拿到的大部分offer是Java服務端研發; 一路走來, 踩了很多坑, 也有了一點小小的心得, 而且部落格已經停更幾個月, 今天就以部落格形式把他記錄下來吧. 2015下半年第一篇部落格, 從最基礎的Java注釋開始:

　　程式員圈有一個笑話

最讨厭在寫代碼的時候寫注釋, 最讨厭别人的代碼裡面不寫注釋.

　　我自己親身經曆:

　　這段時間在微店實習, 第一個接手的項目是将原先北京團隊的代碼遷移到杭州, 由于底層技術架構的更換, 大部分代碼需要重寫, 前提是要了解原先的業務邏輯, 但當我在SVN上把代碼拉下來, 看到意大利面似的一大坨代碼裡隻有寥寥幾行注釋時, 整個人都不好了…

　　另一個遇到場景, 有時自己的代碼有Bug, 或者需要重構, 此時就需要Review代碼, 可是突然發現自己已經很難了解原先邏輯了(很可能這段代碼隻是你前幾天剛剛寫的), 因為我們已經很難回到當時狀态.

　　還有一個重要的原因就是文檔, 往往一個系統被開發出來, 文檔要麼不全, 要麼更新落後, 如果後人要接手這一套系統, 就必須直接閱讀源碼, 如果此時在代碼的關鍵邏輯之處能夠有一兩行注釋提示, 新人就沒有必要絞盡腦汁去猜測當時的設計方案了.

　　後來自己寫代碼時就盡量寫注釋提示, 雖然不一定完全按照下面的注釋規範, 但會盡量用 最簡單的語言把問題闡述清楚, 在邏輯轉折之處添加幾行說明, 無論是自己還是未來的接手人, 都會對現在的你感激不盡.

　　Java提供三種注釋方式: 單行注釋、多行注釋、文檔注釋.

單行/多行注釋

單行注釋與多行注釋的作用就不再贅, IDEA快捷鍵分别如下:

　　 <code>command+/</code>: 以<code>//</code>快速注釋一行或多行 :

　　 <code>command+option+/</code>: 以<code>/**/</code>快速注釋一行或多行

文檔注釋

　　Java提供了一種功能非常強大的注釋形式: 文檔注釋. 如果編寫Java源代碼時添加了文檔注釋, 然後通過JDK提供的javadoc工具就可以直接将代碼裡的注釋提取成一份系統的API文檔. 其注釋形式為<code>/** */</code>

# javadoc 注釋标簽文法

标簽

作用域

說明

@author

類

标明開發該類子產品作者

@version

标明該類子產品的版本

@see

類, 屬性, 方法

參考轉向(相關主題)

@param

方法

對方法中某參數的說明

@return

對方法傳回值的說明

@exception

抛出的異常類型

@throws

與@exception相同

@deprecated

不建議使用該方法

下面是我自己看到和用過的注釋原則:

注釋準确簡潔

内容簡單明了、含義準确, 盡量用最少的語言把問題闡述清楚, 防止注釋的多義性,錯誤的注釋不但無益反而有害.

避免複雜注釋

如果需要用複雜的注釋來解釋代碼, 請檢查此代碼是否應該重寫. 盡一切可能不注釋難以了解的代碼, 最好選擇重構.

TODO List

為尚未完成的代碼添加TODO注釋, 提醒自己還需後續完善.

注釋形式統一

在整個項目中,使用一緻的結構樣式來構造注釋.

注釋與代碼同步更新

邊寫代碼邊注釋,因為以後很可能沒有時間來寫注釋了(可能在今天看來很明顯的東西六周以後或許就不明顯了). 通常描述性注釋先于代碼建立、解釋性注釋在開發過程中建立、提示性注釋在代碼完成之後建立. 修改代碼的同時修改注釋,保證代碼與注釋同步.

注釋就近

保證注釋與其描述的代碼相鄰, 在代碼上方或右方(最好上方)進行注釋.

注釋不要過多

注釋必不可少,但也不應過多,注釋占程式代碼的比例少于20%為宜.注釋是對代碼的“提示”,而不是文檔. 如果代碼本來就一目了然就不加注釋.

删除無用注釋

在代碼傳遞或部署釋出之前, 删除臨時或無關注釋, 避免日後維護中産生混亂.

必加注釋之處

典型算法必有注釋

代碼不明晰處必有注釋

在循環/邏輯分支組成的代碼中加注釋

為他人提供的接口必有注釋

在代碼修改處加修改辨別

類/接口注釋

構造器注釋

方法注釋

字段/屬性注釋

方法内注釋

JSON檢視&amp;編輯

<a href="https://itunes.apple.com/cn/app/regexrx/id498370702?mt=12">RegExRx</a>

Mac上非常好用的正規表達式比對引擎, 用于測試正規表達式書寫的正确與否.

<a href="http://www.iterm2.com/">iTerm2</a>

忘掉Mac自帶的終端吧, iTerm你值得擁有.

<a href="https://www.alfredapp.com/">Alfred</a>

在此隻推薦了我所知道和常用一些小工具, 歡迎同學補充.