文章來源：公衆號-智能化IT系統。
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; /** * 註釋內容 */ |
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.避免在註釋中使用縮寫，特別是不常用縮寫。說明：在使用縮寫時或之前，應對縮寫進行必要的說明。
公衆號-智能化IT系統。每週都有技術文章推送，包括原創技術乾貨，以及技術工作的心得分享。掃描下方關注。
