java提供三種注釋方式: 單行注釋、多行注釋、文檔注釋.
# javadoc 注釋標(biāo)簽語法
| 標(biāo)簽 | 作用域 | 說明 |
|---|---|---|
| @author | 類 | 標(biāo)明開發(fā)該類模塊作者 |
| @version | 類 | 標(biāo)明該類模塊的版本 |
| @see | 類, 屬性, 方法 | 參考轉(zhuǎn)向(相關(guān)主題) |
| @param | 方法 | 對方法中某參數(shù)的說明 |
| @return | 方法 | 對方法返回值的說明 |
| @exception | 方法 | 拋出的異常類型 |
| @throws | 方法 | 與@exception相同 |
| @dePRecated | 方法 | 不建議使用該方法 |
下面是我自己看到和用過的注釋原則:
注釋準(zhǔn)確簡潔 內(nèi)容簡單明了、含義準(zhǔn)確, 盡量用最少的語言把問題闡述清楚, 防止注釋的多義性,錯誤的注釋不但無益反而有害.避免復(fù)雜注釋 如果需要用復(fù)雜的注釋來解釋代碼, 請檢查此代碼是否應(yīng)該重寫. 盡一切可能不注釋難以理解的代碼, 最好選擇重構(gòu).TODO List 為尚未完成的代碼添加TODO注釋, 提醒自己還需后續(xù)完善.注釋形式統(tǒng)一 在整個項目中,使用一致的結(jié)構(gòu)樣式來構(gòu)造注釋.注釋與代碼同步更新 邊寫代碼邊注釋,因為以后很可能沒有時間來寫注釋了(可能在今天看來很明顯的東西六周以后或許就不明顯了). 通常描述性注釋先于代碼創(chuàng)建、解釋性注釋在開發(fā)過程中創(chuàng)建、提示性注釋在代碼完成之后創(chuàng)建. 修改代碼的同時修改注釋,保證代碼與注釋同步.注釋就近 保證注釋與其描述的代碼相鄰, 在代碼上方或右方(最好上方)進(jìn)行注釋.注釋不要過多 注釋必不可少,但也不應(yīng)過多,注釋占程序代碼的比例少于20%為宜.注釋是對代碼的“提示”,而不是文檔. 如果代碼本來就一目了然就不加注釋.刪除無用注釋 在代碼交付或部署發(fā)布之前, 刪除臨時或無關(guān)注釋, 避免日后維護(hù)中產(chǎn)生混亂.必加注釋之處 典型算法必有注釋代碼不明晰處必有注釋在循環(huán)/邏輯分支組成的代碼中加注釋為他人提供的接口必有注釋在代碼修改處加修改標(biāo)識新聞熱點
疑難解答
