代碼註釋規範-IDEA 配置 Java 類方法註釋模板

1. 引言

團隊開發時，業務模塊分配的越清晰，代碼註釋管理越完善，越有利於後面維護，後面再管理也方便不少。另外也起著"文字磚"的作用，你懂的。註釋不需要很詳細，把代碼塊方法塊功能簡述一下就行。不然三月後回頭看就要罵人了，罵完發現是自己寫的，嘖嘖嘖...

三種常用的 Java 註釋方式

<code>    // 聲明常量
    int number;/<code>

<code>    /*
     * 類主函數
     */
    public static void main(String[] args) {
    }/<code>

<code>    /**
     * @param masterId  品牌商Id
     * @param shopId    店鋪Id
     * @param skuId     商品skuId
     * @description: 校驗商品標識碼與店鋪的所屬關係
     * @return: net.jdcloud.APIECRM.model.ValidateSkuUsingGETResponse
     * @author: niaonao
     * @date: 2020/01/13
     */
    public static ValidateSkuUsingGETResponse validateSkuUsing(String masterId, String shopId, String skuId){
        return null;
    }/<code>

2. 自定義註釋模板

2.1 類註釋模板

2.1.1 配置模板

菜單路徑 File-Settings-Editor-File and Code Templates-Incudes-File Header 下添加註釋模板，配置模板後點擊 Apply OK 應用。

自定義註釋模板

<code>/**
 * @className: ${NAME}
 * @description: TODO 類描述 
 * @author: niaonao
 * @date:  ${DATE}
 **//<code>

新建接口文件自動生成註釋，效果如下

<code>/**
 * @className: CrowdService
 * @description: 人群對象業務
 * @author: niaonao
 * @date: 2020/1/13
 **/
public interface CrowdService {
}/<code>

2.1.2 自定義註釋模板不完全變量參考表

2.2 方法註釋模板

2.2.1 配置模板

菜單路徑 File-Settings-Editor-Live Templates 下添加一個新模板組，名字自定義 JavaTemplateGroup。選中模板組，右側點擊新增按鈕，創建新模板。

• Abbreviation 配置為* 。
• Description 自定義描述信息。
• Template Text 自定義模板

<code>*
 $param$
 * @description: TODO
 * @return: $return$
 * @author: niaonao
 * @date: $date$
 *//<code>

Edit variables 編輯變量

• 變量 return 表達式為 methodReturnType()
• 變量 date 表達式為 date()
• 變量 param 表達式為

<code>groovyScript("def result=''; def params=\"${_1}\".replaceAll('[\\\\\\\\[|\\\\\\\\]|\\\\\\\\s]', '').split(',').toList(); for(i = 0; i < params.size(); i++) {result+='* @param: ' + params[i] + ((i < params.size() - 1) ? '\\\\n ' : '')};return result", methodParameters()) /<code>

若有警告信息 No Applicable contexts，點擊 Define 選中 Java 即可。

此處 Expend With 配置為 Enter 回車鍵，註釋生成快捷方式，看個人習慣，也可以時 Tab 鍵。

點擊 Apply OK 應用配置即可。效果如下

<code>    /**
     * @param: masterId
     * @param: shopId
     * @param: skuId
     * @description: TODO
     * @return: net.jdcloud.APIECRM.model.ValidateSkuUsingGETResponse 

     * @author: niaonao
     * @date: 2020/1/13
     */
    public static ValidateSkuUsingGETResponse validateSkuUsing(String masterId, String shopId, String skuId) {
        return null;
    }/<code>

2.2.2 補充說明

方法註釋模板不可用在，方法外，若用在方法外 @param 獲取不到，註釋為 @param null;

類註釋模板在文件創建時生成，已創建文件不會觸發該模板，會觸發方法註釋模板。

閱讀更多 鹹魚技術棧 的文章

關鍵字: 代碼 註釋 模板