# Java 注釋 > 原文： [https://howtodoinjava.com/java/basics/java-comments/](https://howtodoinjava.com/java/basics/java-comments/) 了解有關 **Java 注釋**，**Java 注釋的類型**， **Javadoc** 工具，**注釋的性能影響**和需要遵循的**最佳做法**的所有信息。 ## 1\. 為什么要編寫 Java 注釋？ 顧名思義， [Java](https://howtodoinjava.com/java/basics/what-is-java-programming-language/) 注釋是出于各種原因在程序之間編寫的注釋。 例如，您可以將注釋寫給： * 編寫有關變量，方法，類或任何語句的信息或說明。 * 編寫可在 Java 文檔中使用的文本。 * 隱藏特定時間的程序代碼，等等。 #### 1.1 Java 注釋示例 給定的代碼是 Java 注釋的**示例**，以及如何使用它們。 ```java /** * Contains method to greet users by their name and location. * * @author Lokesh Gupta */ public class Main { /** * Launches the application * * @param args - Application startup arguments */ public static void main(String[] args) { getMessage("Lokesh", "India"); } /** * Returns welcome message for a customer by customer name and location * * @param name - Name of the visitor * @param region - Location * @return - Welcome message */ public static String getMessage (String name, String region) { StringBuilder builder = new StringBuilder(); builder.append("Hello "); builder.append(name); builder.append(", Welcome to "); builder.append(region); builder.append(" !!"); return builder.toString(); } } ``` ## 2\. Java 注釋的類型 Java 中有 **3 種類型的注釋**。 1. #### 單行注釋 當注釋只能寫在一行中時，請使用單行注釋。 這些注釋是通過 Java 語句編寫的，以闡明它們在做什么。 ```java //Initialize the counter variable to 0 int counter = 0; ``` 2. #### 多行注釋 當您需要在源代碼中添加超過一行的信息時，請使用多行注釋。 多行注釋通常用于代碼塊上方，這些代碼塊具有無法單行編寫的復雜邏輯。 ```java /* * This function returns a variable which shall be used as a counter for any loop. * Counter variable is of integer type and should not be reset during execution. */ public int getCounter() { // } ``` 3. #### 文檔注釋 當您想公開要由`javadoc`工具獲取的信息時，將使用文檔注釋。 這是您在使用**自動完成**特性時在編輯器（例如，日食）中看到的信息。 這些注釋位于類，接口和方法定義之上。 > 文檔注釋以`/**`開頭，以`*/`結尾。 您可以在這些注釋中使用 **javadoc 注解**，例如 `@param`和`@return`。 ```java /** * This function returns a variable which shall be used as a counter for any loop. * Counter variable is of integer type and should not be reset during execution. * * @param seed - initial value of the counter * @return counter value */ public int getCounter(int seed) { // } ``` 文檔注釋是編程不可或缺的一部分，不應跳過。 ## 3\. 注釋快捷方式 在 Eclipse IDE 中，只需在公共方法或類之前鍵入`/**[Enter]`，它將自動在所有必要的`@param`，`@author`和`@return`屬性中生成。  Eclipse 中的 Java 注釋快捷方式 ## 4\. `javadoc`工具 **javadoc** 工具與 JDK 發行版捆綁在一起。 它將它們轉換為標準化，格式清晰，易于閱讀的網頁。 它從文檔注釋生成 **API 文檔**。 #### 4.1 從命令提示符運行`javadoc` 首先，確保`javadoc`工具位于**路徑**中。 如果沒有，則將 JDK `/bin`文件夾添加到`PATH`變量。 ```java $ set PATH=.;C:\BAML\DFCCUI\installs\jdk1.8.0_31\bin ``` 要生成 Java 文檔，請執行帶有兩個參數的工具。 首先是生成的 Java 文檔的**位置**，其次是 **Java 源文件**。 在我們的情況下，我從`Main.java`所在的位置執行了此命令。 ```java $ javadoc -d C:/temp Main.java ``` 它生成了這些 Java 文檔 HTML 文件。  生成的 Java 文檔 #### 4.2 從 Eclipse 運行`javadoc` 您也可以從 Eclipse IDE 生成 Java 文檔。 遵循以下簡單步驟： 1. 在**包瀏覽器**中，右鍵單擊所需的項目/包。 2. 選擇`Export.../Javadoc`并點擊`Next`.  導出 Java 文檔選項 3. 默認情況下，將選擇整個源代碼。 驗證并更改您的選擇。  Eclipse 中的 Java Doc 選項 4. 您可以選擇“ `Private`”來生成可見性級別。 這將生成所有可能的 Javadocs，即使是私有方法也是如此。 5. 選擇“ `standard doclet`”，它是文檔的目標文件夾。 6. 點擊`Next`。 7. 輸入一個有意義的`Document title`并單擊`Finish`。 如果正確執行上述所有步驟，則將生成與我們在命令提示符選項中看到的類似的 Java 文檔文件。 ## 5\. Java 注釋對性能的影響 Java 代碼中的實現注釋僅供人們閱讀。 Java 注釋是編譯器未編譯的語句，因此它們不包含在已編譯的字節碼（`.class`文件）中。 這就是 **Java 注釋對應用程序性能**也沒有影響的原因。 ## 6\. Java 注釋最佳實踐 請遵循這些**最佳做法**在您的應用程序源代碼中包含適當的注釋。 1. 不要在源代碼中使用不必要的注釋。 如果您的代碼需要比正常解釋更多的內容，則可以重構您的代碼。 2. 保持注釋縮進一致并匹配以實現最佳可讀性。 3. 注釋是針對人類的，因此請使用簡單的語言進行解釋。 4. 始終在源代碼中添加文檔注釋。 學習愉快！ 閱讀更多： [Oracle 針對 Javadoc 的建議](http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html) [Javadoc 標記參考](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#javadoctags)