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