代碼注釋及編碼技巧(Java版)

工欲善其事，必先利其器！

個(gè)人以為，寫代碼不加注釋，態(tài)度是不端正的。一來注釋能讓別人看懂并上手，易交接工作；二來過一段時(shí)間你修改BUG的時(shí)候，能很快捋清脈絡(luò)。

1 注釋模板

1.1 規(guī)約介紹

無規(guī)矩不成方圓，在講注釋模板前，我們先講規(guī)范。要說規(guī)范哪家強(qiáng)？當(dāng)然是阿里巴巴出的Java規(guī)約了。

alibaba/p3c：該開源項(xiàng)目有什么？

1.阿里巴巴Java開發(fā)手冊(cè).pdf,該pdf是大綱性的東西，沒有經(jīng)驗(yàn)的新手估計(jì)看不懂。

2.《碼出高效》,這本書針對(duì)pdf列出了例子來講解問題。

3.IDE plugin,看了上面兩本書還怕犯錯(cuò)？沒關(guān)系，還有IDE插件(針對(duì)IDEA和Eclipse)能幫你編碼的時(shí)候檢查是否符合規(guī)約。

1.2 注釋約定

在阿里巴巴的規(guī)約中，有如下規(guī)定：

  • 【強(qiáng)制】類、類屬性、類方法的注釋必須使用 Javadoc 規(guī)范，使用//** 內(nèi)容 */格式，不得使用// xxx方式。

  • 【強(qiáng)制】方法內(nèi)部單行注釋，在被注釋語句上方另起一行，使用// 內(nèi)容注釋。方法內(nèi)部多行注釋使用/* 內(nèi)容 */注釋，注意與代碼對(duì)齊。

  • 【說明】在 IDE 編輯窗口中，Javadoc 方式會(huì)提示相關(guān)注釋，生成 Javadoc 可以正確輸出相應(yīng)注釋；在 IDE中，工程調(diào)用方法時(shí)，不進(jìn)入方法即可懸浮提示方法、參數(shù)、返回值的意義，提高閱讀效率。

  • ................

當(dāng)然還有很多說明，此處就概括說明一下：

IDEA注釋快捷鍵

單行注釋(// 內(nèi)容)：Ctrl + /
塊注釋(/* 內(nèi)容 */)：Ctrl + Shift + /
說明注釋(/** 內(nèi)容 */)：/** + Enter (通常在方法名上方敲擊。也可自己做成模板)

1.方法內(nèi)部只能使用單行注釋與塊注釋

2.除卻方法內(nèi)部注釋外，其余所有注釋均使用說明注釋

3.所有注釋都必須位于代碼上方

PS：關(guān)于什么是Javadoc規(guī)范或者Javadoc注釋標(biāo)簽，請(qǐng)自行百度。

1.3 IDEA注釋模板

1.3.1 類注釋模板

類注釋

請(qǐng)按箭頭順序去理解。

  • Reformat according to style，是否格式化注釋。如果格式化，有可能會(huì)打亂@xxx的順序。

可以看到，只要在模板上加上這么一段即可：

/**
 * ${description}
 * @author ${USER}
 * @create ${DATE} ${TIME}
 */

在新建類的時(shí)候就會(huì)自動(dòng)生成注釋了。

需要說明的是：

  • .如果你的${xxx} 不存在于模板右下角的Description列表里，新建類時(shí)會(huì)自動(dòng)彈出一個(gè)框，讓你補(bǔ)上所有的${xxx}信息。

  • .比如該模板中我增加了一個(gè)不存在于列表的 ${description}，當(dāng)我新建類時(shí)：

    填寫占位符的信息

新建類

1.3.2 方法注釋模板

由于方法參數(shù)的不確定性，這里使用一點(diǎn)技巧來自動(dòng)生成Javadoc規(guī)范的參數(shù)。

1.創(chuàng)建自己的Template Group：

MyGroup

2.創(chuàng)建第一個(gè)Live Template：

one_live.png
  • Template Text如下：

第一個(gè)星號(hào)前面是沒有空格的，余下的星號(hào)前面都有一個(gè)空格存在。這里最容易出錯(cuò)。

*
 * [方法描述]
$param$
 * @return $return$
 * @author $user$
 * @create $date$ $time$
 */
  • 為該Live Template設(shè)置參數(shù)值。點(diǎn)擊 Edit variables,設(shè)置自定義的 $xxx$參數(shù)：
one_live_values.png

這里的param不必選擇Expresstion表達(dá)式，只需要填寫Default value即可：

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())

3.創(chuàng)建第二個(gè)Live Template：

two_live.png

其中 Change最開始為Define，只有選定了Live Template的范圍才會(huì)變成Change。一般圈定范圍為Java。而Options 的 Exand with 則根據(jù)個(gè)人習(xí)慣了。這里我兩個(gè)都選擇Enter。

Live Template 是如何生效的？

  • 設(shè)定的 abbreviation(縮寫的意思) + 設(shè)定的 Expand with
  • 該模板【使用方法】：在方法名的上方敲，mc + 連續(xù)兩次 Enter
mc.gif

至此，方法模板就結(jié)束了，關(guān)于模板的縮寫設(shè)置，看個(gè)人習(xí)慣更改。

1.3.2 顯示Javadoc注釋

Ctrl + q :查看Javadoc文檔
這里我準(zhǔn)備一個(gè)遵守注釋規(guī)約的Java文件：

package com.pcp.demo;
/**
 * 我是類描述：成員變量與方法模板演示
 * @author chaopeng
 * @create 2019/7/13 21:57
 */
public class JavaTemplate {

    /** 我是成員變量1的注釋 */
    public double field1 = 1;
    /** 成員變量2 */
    public double field2 = 2;
    /** 成員變量3 */
    public double field3 = 3;

    /**
     * 我是方法描述：方法演示
     * @param param1 我是參數(shù)1描述 參數(shù)超鏈接{@link JavaTemplate#field1}
     * @param param2 我是參數(shù)2描述
     * @param param3 我是參數(shù)3描述
     * @return void 無返回值
     * @author chaopeng
     * @create 2019/7/14 17:29
     */
    public void m1(double param1,int param2,String param3) {

    }
}

在這個(gè)JavaTemplate.java文件中，符合Javadoc標(biāo)簽的有：

@param，表示參數(shù)
@return，表示返回值
{@link xxx}，表示可以跳轉(zhuǎn)的超鏈接
當(dāng)我們調(diào)用方法時(shí)，按一下 Ctrl + q，就能看到之前寫的注釋了

Javadoc.gif

2 編碼技巧

類的編寫，無非是類成員、類方法以及局部變量。

我們平時(shí)是如何寫成員變量和方法的？無非就是按順序?qū)憽?/p>

field_write.gif

2.1 編寫成員變量的6種模板

  • 實(shí)際只是省略public或private或= 或;
  • 空格變成了Enter，寫代碼只需一路Enter
  • 在自己的Template Group里新建6個(gè)Live Template
  • 可自定義Live Template的$xxx$占位符名稱

1.私有成員變量,不初始化，縮寫：f.prif

private $field_type$ $field_name$;

2.私有成員變量,需初始化，縮寫：f.prit

private $field_type$ $field_name$ = $field_value$;

3.公有成員變量,不初始化，縮寫：f.pubf

public $field_type$ $field_name$;

4.公有成員變量,需初始化，縮寫：f.pubt

public $field_type$ $field_name$ = $field_value$;

5.局部變量，不初始化，縮寫：vf

$method_var_type$ $method_var$;

6.局部變量，需初始化，縮寫：vt

$method_var_type$ $method_var$ = $var_value$;

一路Enter，不使用空格(看個(gè)人習(xí)慣)：

field.gif

2.2 編寫方法的4種模板

  • 實(shí)際只是省略public或private或() 或{}或;或void
  • 空格變成了Enter，寫代碼只需一路Enter
  • 在自己的Template Group里新建4個(gè)Live Template
  • 可自定義Live Template的$xxx$占位符名稱

1.私有方法，有返回值，縮寫：m.pri.unvoid

private $method_type$ $method_name$($method_params$) {
    $method_content$
    return $method_return$;
}

2.私有方法，無返回值，縮寫：m.pri.void

private void $method_name$($method_params$) {
    $method_content$
}

3.公有方法，有返回值，縮寫：m.pub.unvoid

public $method_type$ $method_name$($method_params$) {
    $method_content$
    return $method_return$;
}

4.公有方法，無返回值，縮寫：m.pub.void

public void $method_name$($method_params$) {
    $method_content$
}

一路Enter，寫多個(gè)參數(shù)時(shí)要使用空格：

method.gif

這里就不講Eclipse的模板設(shè)置了，事實(shí)上它內(nèi)部已經(jīng)集成了各種設(shè)置，只需要在對(duì)應(yīng)的位置按下：Alt + Shift + j就會(huì)自動(dòng)出現(xiàn)相應(yīng)的注釋了，百度有很多教程。

最后，稍微提下小技巧：

  • 寫完變量想新開下一行？

Shift + Enter

  • 寫完變量想新開上一行？

Ctrl + Altt + Enter

  • 方法內(nèi)部寫完了想添加方法注釋？
  • Ctrl + {，跳到方法體的 {
  • Ctrl + Alt + Enter，在方法名上方新開一行
  • mc + 連續(xù)兩次Enter，添加注釋
  • 方法注釋寫完了想繼續(xù)添加方法？
  • Ctrl + }，跳到類的}
  • Ctrl + Alt + Enter，在類的}上方新開一行
  • 編寫方法
  • 方法內(nèi)部寫完了想跳出方法體？
  • Ctrl + }，跳到方法體的}
  • Shift + Enter
  • 最后別忘了格式化代碼：
  • Ctrl + Alt + L

PS:多記IDEA快捷鍵就對(duì)了。

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容