轉(zhuǎn)載：https://zhuanlan.zhihu.com/p/32725482
前言
今天我們來說說如何編寫Java注釋。使用過Java的同學(xué)都非常熟悉尺碰，Java中有:
- 單行注釋
// 這是單注釋 - 多行注釋
/*這是多行注釋*/ - Javadoc注釋
/**這是javadoc注釋*/
其實(shí)這里面還有很多細(xì)節(jié)呢，下面我們一一來揭曉
哪些地方需要添加注釋
首先婶熬，我們需要確定一下为狸，添加注釋的目的是什么？(手動(dòng)思考10秒)荐捻。
我認(rèn)為添加注釋，是為了程序更容易理解與維護(hù)寡夹，特別是維護(hù)处面，更是對(duì)自己代碼負(fù)責(zé)的一種體現(xiàn)。
那基于這樣的目的菩掏，在日常開發(fā)中魂角，我們需要在哪些地方添加注釋呢？
- 類智绸，接口野揪。
這一部分注釋是必須的。在這里瞧栗，我們需要使用javadoc注釋斯稳，需要標(biāo)明，創(chuàng)建者迹恐，創(chuàng)建時(shí)間挣惰，版本，以及該類的作用殴边。如下所示:
package com.andyqian.utils;
/**
* @author: andy
* @date: 18-01-05
* @version: 1.0.0
* @description: 生成PDF 工具類
*/
public class PdfUtil {
}
- 方法
在方法中通熄，我們需要對(duì)入?yún)ⅲ鰠⒄叶迹约胺祷刂担獦?biāo)明廊酣。如下所示：
/**
* 生成pdf文件
* @param htmlContent 待生成pdf的 html內(nèi)容
* @param file 生成pdf文件地址
* @see PdfUtils#getFontPath()
* @return true 生成成功 false 生成失敗
*/
public static boolean generatePdf(String htmlContent,File file){
...
return result;
}
- 常量
對(duì)常量能耻，我們需要使用多行注釋，進(jìn)行標(biāo)明該常量的用途，如下所示:
/**
* @author: andy
* @date: 18-01-05
* @version: 0.0.1
* @description:
*/
public class StatusConsts {
/**
* 博客地址
*/
public static final String BLOG="www.andyqian.com";
}
- 關(guān)鍵算法上
在關(guān)鍵算法上晓猛，添加注釋并且按照順序依次標(biāo)明饿幅，寫明白該方法為什么這么做。如下所示:
/**
* 應(yīng)用場景:
* 1.在windows下,使用Thread.currentThread()獲取路徑時(shí),出現(xiàn)空對(duì)象戒职，導(dǎo)致不能使用
* 2.在linux下,使用PdfUtils.class獲取路徑為null,
* 獲取字體路徑
* @return 返回字體路徑
*/
private static String getFontPath(){
String path="";
// 1.
ClassLoader classLoader= Thread.currentThread().getContextClassLoader();
URL url = (classLoader==null)?null:classLoader.getResource("/");
String threadCurrentPath = (url==null)?"":url.getPath();
// 2\. 如果線程獲取為null,則使用當(dāng)前PdfUtils.class加載路徑
if(threadCurrentPath==null||"".equals(threadCurrentPath)){
path = PdfUtils.class.getClass().getResource("/").getPath();
}
// 3.拼接字體路徑
StringBuffer stringBuffer = new StringBuffer(path);
stringBuffer.append("/fonts/SIMKAI.TTF");
path = stringBuffer.toString();
return path;
}
怎么添加注釋?
1. IDEA 自動(dòng)生成
對(duì)于類中的注釋栗恩，我們可以通過IDEA自動(dòng)生成。
如IDEA 可以通過：File->Settings->Editor->File and Code Templates->Includes->File Header來設(shè)置模板洪燥，這樣新建文件時(shí)磕秤，IDEA會(huì)按照設(shè)置的模板，會(huì)自動(dòng)生成一個(gè)注釋捧韵，就不需要一個(gè)一個(gè)敲了市咆。
</figure>
其中標(biāo)簽有:
${USER} : 當(dāng)前用戶。
${DATE} : 當(dāng)前日期再来。
${PACKAGE_NAME}：包名蒙兰。
${TIME}: 當(dāng)前時(shí)間。
${YEAR}： 當(dāng)前年芒篷。
${MONTH}：當(dāng)前月搜变。
${DAY}: 當(dāng)前日。
${HOURS}： 當(dāng)前小時(shí)针炉。
${MINUTE}: 當(dāng)前分鐘
- 注釋引用
如果方法中引用了其他的方法挠他，在注釋中如何體現(xiàn)呢？細(xì)心的朋友糊识，應(yīng)該已經(jīng)發(fā)現(xiàn)了绩社，在上面的：
/**
* 生成pdf文件
* @param htmlContent 待生成pdf的 html內(nèi)容
* @param file 生成pdf文件地址
* @see PdfUtils#getFontPath()
* @return true 生成成功 false 生成失敗
*/
public static boolean generatePdf(String htmlContent,File file){
...
return result;
}
中的@see就有這個(gè)作用，其語法是:
@see package.class#method label
@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)
@see #constructor(Type, Type,...)
@see #constructor(Type argname, Type argname,...)
例如:
@see PdfUtils#getFontPath()
如果是同一個(gè)類中赂苗，package(包名全路徑)可以省略愉耙。有相同功能的標(biāo)簽有:
{[@link](http://link.zhihu.com/?target=https%3A//my.oschina.net/u/393) package.class#metod}
/**
* 生成pdf文件
* @return true 生成成功 false 生成失敗
* @throws Exception
* {@link PdfUtils#getFontPath()}
*/
public static boolean generatePdf(String htmlContent,File file){
....
}
其區(qū)別是：@see必須要在注釋行首，{@link}可以在任意位置拌滋。
- 在IDEA中朴沿，我們可以選中方法通過快捷鍵
Ctrl+D即可查看我們添加的注釋，如下圖所示:
</figure>
- 如果需要引用外網(wǎng)的連接败砂，我們可以通過HTML標(biāo)簽中的a標(biāo)簽來表示赌渣，如下所示:
@see <a >博客地址</a>
以下為javadoc 需要熟知的注釋標(biāo)簽:
@see 引用類/方法。
@author: 作者昌犹。
@date：日期坚芜。
@version: 版本號(hào)。
@throws：異常信息斜姥。
@param：參數(shù)
@return： 方法返回值鸿竖。
@since: 開源項(xiàng)目常用此標(biāo)簽用于創(chuàng)建日期 沧竟。
{@value}: 會(huì)使用該值，常用于常量缚忧。
{@link} 引用類/方法悟泵。
{@linkplain} 與@link功能一致。
完整案例如下:
package com.andyqian.pdf.utils;
import com.itextpdf.text.log.Logger;
import com.itextpdf.text.log.LoggerFactory;
import java.io.File;
import java.net.URL;
/**
* @author: 鞠騫
* @date: 18-01-05
* @version: 1.0.0
* @description: 生成PDF 工具類
*/
public class PdfUtils {
private static final Logger logger = LoggerFactory.getLogger(PdfUtils.class);
/**
* 生成pdf文件
* @param htmlContent 待生成pdf的 html內(nèi)容
* @param file 生成pdf文件地址
* @see <a >https://itextpdf.com/</a>
* @return true 生成成功 false 生成失敗
*/
public static boolean generatePdf(String htmlContent,File file)throws Exception{
...
return true;
}
/**
* 應(yīng)用場景:
* 1.在windows下,使用Thread.currentThread()獲取路徑時(shí),出現(xiàn)空對(duì)象闪水，導(dǎo)致不能使用
* 2.在linux下,使用PdfUtils.class獲取路徑為null,
* 獲取字體路徑
* @return 返回字體路徑
*/
private static String getFontPath(){
String path="";
// 1.
ClassLoader classLoader= Thread.currentThread().getContextClassLoader();
URL url = (classLoader==null)?null:classLoader.getResource("/");
String threadCurrentPath = (url==null)?"":url.getPath();
// 2\. 如果線程獲取為null,則使用當(dāng)前PdfUtils.class加載路徑
if(threadCurrentPath==null||"".equals(threadCurrentPath)){
path = PdfUtils.class.getClass().getResource("/").getPath();
}
// 3.拼接字體路徑
StringBuffer stringBuffer = new StringBuffer(path);
stringBuffer.append("/fonts/SIMKAI.TTF");
path = stringBuffer.toString();
return path;
}
}
添加注釋時(shí)的一點(diǎn)建議
- 類中糕非，接口等必須有創(chuàng)建時(shí)間，創(chuàng)建人球榆，版本號(hào)朽肥，描述等注釋。
- 注釋不是越多越好芜果，比如：get/set方法就不需要寫注釋鞠呈。更不需要每一行都寫注釋。
- 注釋需要寫的簡明易懂右钾。特別是方法的參數(shù)蚁吝，以及返回值。
- 每一次修改時(shí)舀射，相應(yīng)的注釋也應(yīng)進(jìn)行同步更新窘茁。
- 在類，接口脆烟，方法中山林，應(yīng)該都使用
/** */javadoc注釋。因?yàn)檫@樣調(diào)用者就不需要進(jìn)入方法內(nèi)部才知道方法的用處邢羔。提高編碼效率驼抹。 - 方法代碼中如果有順序之分，最好將代碼也加上序號(hào)拜鹤，如1框冀，2，3等敏簿。
- 枚舉中的每一個(gè)值都需要添加注釋明也。
小結(jié)
寫注釋是一個(gè)好習(xí)慣，能讓自己和團(tuán)隊(duì)都受益惯裕，如果你接手一個(gè)一丁點(diǎn)注釋都沒有的項(xiàng)目温数，那么上一個(gè)程序員就倒霉了(此處省略N個(gè)字)，不知你們有沒有看過開源項(xiàng)目的源碼蜻势，那注釋寫的相當(dāng)詳細(xì)撑刺，大家可以多多參考，爭取別做一個(gè)”倒霉”的程序員握玛。
轉(zhuǎn)載：https://zhuanlan.zhihu.com/p/32725482
