注釋在編程中扮演著非常重要的角色，它們是寫給人類閱讀的，而不是給計算機執行的。良好的注釋可以極大地提高代碼的可讀性和可維護性。
為什么需要注釋？
- 提高可讀性： 注釋可以解釋代碼的功能、實現思路、特殊處理等，幫助其他開發者（或者未來的你）更容易理解代碼的意圖
- 方便維護： 當代碼需要修改或維護時，清晰的注釋能夠幫助開發者快速定位需要修改的部分，并理解修改可能帶來的影響
- 生成文檔： 特定格式的注釋（Javadoc）可以被工具自動提取，生成專業的 API 文檔
- 調試代碼： 在調試過程中，可以使用注釋臨時禁用某些代碼塊，方便定位問題
- 作為備忘： 開發者可以在代碼中添加一些臨時的想法或注意事項
Java 支持三種類型的注釋：
1. 單行注釋 (Single-line Comments)
以雙斜線 // 開頭，直到行尾的內容都被視為注釋。單行注釋通常用于解釋代碼中的某一行或一小段代碼的功能。
// 這是一個單行注釋
int age = 30; // 聲明一個整型變量 age 并賦值為 30
2. 多行注釋 (Multi-line Comments)
以 /* 開頭，以 / 結尾。/ 和 */ 之間的所有內容都被視為注釋，可以跨越多行。多行注釋通常用于解釋一段較長的代碼塊、一個方法或一個類的整體功能。
/** 這是一個多行注釋。* 它可以跨越多行，* 用于解釋一段代碼的功能或者提供更詳細的說明。*/
public class MyClass {// ... 類的內容 ...
}
:::color3
多行注釋不能嵌套使用。也就是說，在一個多行注釋內部不能再包含另一個 /* ... */ 注釋。
:::
3. 文檔注釋 (Documentation Comments) - Javadoc
文檔注釋是一種特殊的多行注釋，以 /** 開頭，以 */ 結尾。文檔注釋主要用于為類、接口、方法、構造器、字段和枚舉常量生成 API 文檔。Javadoc 工具可以解析這些注釋，并生成 HTML 格式的文檔。
文檔注釋的內容可以包含特殊的標簽（以 @ 開頭），用于描述不同的方面，例如參數、返回值、異常、作者、版本等。
/*** 這是一個表示一個簡單計算器的類。* 它提供了加法和減法運算。** @author John Doe* @version 1.0* @since 1.0*/
public class Calculator {/*** 將兩個整數相加。** @param a 第一個整數* @param b 第二個整數* @return 兩個整數的和* @throws ArithmeticException 如果發生算術錯誤（雖然在這個例子中不會發生）*/public int add(int a, int b) {return a + b;}/*** 從第一個整數中減去第二個整數。** @param a 被減數* @param b 減數* @return 兩個整數的差*/public int subtract(int a, int b) {return a - b;}
}
常用的 Javadoc 標簽包括：
@author：標識作者。@version：標識版本號。@param：描述方法的參數，后面跟著參數名和描述。@return：描述方法的返回值。@throws或@exception：描述方法可能拋出的異常，后面跟著異常類名和描述。@since：標識從哪個版本開始引入。@deprecated：標識該元素已過時，并說明替代方案。
因為 IDEA 創建的 Java 類是沒有類注釋的，所以，我一般習慣在 IDEA 中創建一個類文檔注釋模板，讓后配置對應的觸發字符，輸入觸發字符就能快速的生成類的文檔注釋：
/***** @author jxd* {@code @date} $DATETIME$*/
date("yyyy/MM/dd HH:mm")
在已創建的類上使用 *head ，然后按下 Enter 鍵，就會自動生成文檔注釋模板。
編寫良好注釋的建議
- 保持注釋的簡潔和清晰： 注釋應該易于理解，避免使用過于晦澀的術語或過長的段落。
- 注釋應該準確地反映代碼的功能： 當代碼修改時，務必更新相關的注釋，確保它們與代碼保持一致。
- 解釋代碼的意圖，而不是僅僅描述代碼做了什么： 好的注釋應該解釋 為什么 這段代碼是這樣寫的，而不是簡單地重復代碼本身。
- 為重要的代碼塊、方法和類添加注釋： 特別是那些邏輯復雜、容易產生誤解或者對外提供的 API。
- 使用文檔注釋 (Javadoc) 為公共 API 生成文檔： 這有助于其他開發者了解如何使用你的代碼。
- 避免過度注釋： 對于顯而易見的代碼，不一定需要添加注釋。過多的注釋反而會使代碼顯得冗余。
- 使用統一的注釋風格： 保持整個項目注釋風格的一致性，提高代碼的整體可讀性。
- 及時刪除不再需要的注釋： 例如，一些臨時的調試代碼注釋在問題解決后應該被刪除。
