Java注釋規範簡介說明

​​轉自:http://www.java265.com/JavaCourse/202111/1725.html​​

下文筆者講述java中注釋規範的相關說明，如下所示:

注釋形式統一

在整個團隊中，我們應該遵循同一種注釋規範，可通過設定注釋模闆的方式，使用java注釋變得規範

注釋的簡潔

通過注釋，可直接得到下面代碼的功能，為程式後續維護提供便利

注釋的一緻性

在編寫代碼之前或同步進行代碼注釋的編寫

修改代碼時，也同時修改注釋

注釋的位置

使代碼同注釋相鄰，避免出現代碼和注釋無法對應，長年累月後都不知道注釋所對應的代碼

注釋的數量

整個代碼中，注釋不宜過多，但也不能太少

删除無用注釋

删除注釋中的臨時内容及無用的注釋資訊，避免後續維護時，給人誤導行為

複雜的注釋

避免編寫令人難以了解的注釋

多餘的注釋

當有些代碼非常清晰時，我們應該避免加入一些無關緊要的注釋資訊

必加的注釋

如：一些實作子類中，算法中，我們如果不加入注釋，則讓後人無法了解相應的代碼

注釋不會增加檔案的大小

Java中的注釋檔案不會增加檔案的大小

java注釋示例

檔案頭注釋

檔案頭注釋以/*開始，以*/結束，需要注明該檔案的建立時間、檔案名、命名空間資訊

如：

/* Created on 2021-11-16
     * File User.java
     * Package com.Java265.other
     * Create Date:2021-11-16
     */      

類、接口注釋

類、接口的注釋采用/**...*/

描述部分用來書寫該類的作用或者相關資訊，塊标記部分必須注明作者個版本

例：

/** Title：XXXX OCR
     * Description:XXXX OCR 3.0
     * Copyright:Copyright(c) 2021
     * Company:XXXX 有限公司
     * 
     * @author Adeal
     * @version 3.0
     */      

構造函數注釋

構造函數注釋采用/**...*/

描述部分注明構造函數的作用

/**
     * 預設構造函數
     */
帶塊标記的示例如下：

/**
     * 帶參數構造函數，初始化模式名、變量名稱和資料源類型
     * @param schema
     * Ref 模式名
     * @param name
     * Ref 變量名稱
     * @param type
     * by Val 資料源類型
     */      

域注釋

域注釋可以出現在注釋文檔裡面

也可以不出現在注釋文檔裡面

用/**...*/的域注釋将會被認為是注釋文檔而出現在最終生成的HTML報告裡面（Javadoc）

而使用/*...*/的注釋則會被忽略掉

如：

/**
     * @作者 XXX
     * @建立時間 Jan 16,2021 05:05:11 AM
     */      

方法注釋

方法注釋采用/**...*/

描述部分注明方法的功能

/**
     * 求最大公約數
     *
     * @param int a
     *  a:待求公約數的參數
     */