原文：https://blog.csdn.net/weixin_42488570/article/details/80760849 
 

1.在有處理邏輯的程式碼中，源程式有效註釋量必須在20％以上。

說明：註釋的原則是有助於對程式的閱讀理解，在該加的地方都加了，註釋不宜太多也不能太少，註釋語言必須準確、易懂、簡潔。

2.檔案註釋：檔案註釋寫入檔案頭部。

說明：以/* 開始

示例：

/ *
* 檔名：[檔名]
* 作者：〈版權〉
* 描述：〈描述〉
* 修改人：〈修改人〉
* 修改時間：YYYY-MM-DD
 * 修改內容：〈修改內容〉
  */
 

說明：每次修改後在檔案頭部寫明修改資訊。

示例：

/ *
* 檔名：LogManager.java
* 版權：Copyright 2000-2001 Huawei Tech. Co. Ltd.  All Rights Reserved.
* 描述： WIN V200R002 WEBSMAP 通用日誌系統
* 修改人：張三
* 修改時間：2001-02-16
* 修改內容：新增
* 修改人：李四
* 修改時間：2001-02-26
* 修改內容：。。。。。。
* 修改人：王五
* 修改時間：2001-03-25
* 修改內容：。。。。。。
 */

3.類和介面的註釋：該註釋放在class定義之前，using或package關鍵字之後。

示例：

package com. websmap.comm;
/**
 * 註釋內容
 */
 public class CommManager
 

4.類和介面的註釋內容：類的註釋主要是一句話功能簡述、功能詳細描述，說明：可根據需要列出：版本號、生成日期、作者、內容、功能、與其它類的關係等。

格式：

/ *
 * 〈一句話功能簡述〉
* 〈功能詳細描述〉
* @author [作者]
* @version [版本號, YYYY-MM-DD]
* @see [相關類/方法]
* @since [產品/模組版本]
* @deprecated
*/
說明：描述部分說明該類或者介面的功能、作用、使用方法和注意事項，每次修改後增加作者和更新版本號和日期，@since 表示從那個版本開始就有這個類或者介面，@deprecated 表示不建議使用該類或者介面。

示例：

/ *
* LogManager 類集中控制對日誌讀寫的操作。
*全部為靜態變數和靜態方法，對外提供統一介面。分配對應日誌型別的讀寫器，讀取或寫入符合條件的日誌紀錄。
* @author 張三，李四，王五
* @version 1.2, 2001-03-25
* @see LogIteraotor
* @see BasicLog
* @since CommonLog1.0
*/

5.類屬性、公有和保護方法註釋：寫在類屬性、公有和保護方法上面。用//來註釋,需要對齊被註釋程式碼。

示例：

/ /註釋內容
private  String logType
 

6.成員變數註釋內容：成員變數的意義、目的、功能，可能被用到的地方。用//來註釋,需要對齊被註釋程式碼

7.公有和保護方法註釋內容：列出方法的一句話功能簡述、功能詳細描述、輸入引數、輸出引數、返回值、違例等。
格式：

/ **
*〈一句話功能簡述〉
*〈功能詳細描述〉
* @param [引數1] [引數1說明]
* @param [引數2] [引數2說明]
* @return [返回型別說明]
* @exception/throws [違例型別] [違例說明]
* @see [類、類#方法、類#成員]
 * @deprecated
*/
說明：@since 表示從那個版本開始就有這個方法；@exception或throws 列出可能出現的異常；@deprecated 表示不建議使用該方法。

8.對於方法內部用throw語句丟擲的異常，必須在方法的註釋中標明，對於所呼叫的其他方法所丟擲的異常，選擇主要的在註釋中說明。對於非RuntimeException ，即throws子句宣告會丟擲的異常，必須在方法的註釋中標明。

說明：

異常註釋用@exception或@throws表示，在JavaDoc中兩者等價，但推薦用@exception標註Runtime 異常，@throws標註非Runtime 異常。異常的註釋必須說明該異常的含義及什麼條件下丟擲該異常。

9.註釋應與其描述的程式碼相近，對程式碼的註釋應放在其上方或右方（對單條語句的註釋）相鄰位置，不可放在下面，如放於上方則需與其上面的程式碼用空行隔開。

10.註釋的排版，按照上述示例來展示。

11.註釋應該放在被註釋的程式碼前面，分行展示，但中間不留空行。

12.對變數的定義和分支語句（條件分支、迴圈語句等）必須編寫註釋。

說明：分支語句往往是程式實現某一特定功能的關鍵。

13.邊寫程式碼邊註釋，修改程式碼同時修改相應的註釋，以保證註釋與程式碼的一致性。不再有用的註釋要刪除。

14.註釋的內容要清楚、明瞭，含義準確，防止註釋二義性。說明：錯誤的註釋不但無益反而有害。

15.避免在註釋中使用縮寫，特別是不常用縮寫。說明：在使用縮寫時或之前，應對縮寫進行必要的說明。