Java評論：並非一切都那麼簡單

介紹

評論- 看起來可以更簡單，為什麼要寫整篇文章。但事情沒那麼簡單。正如我老闆所說，任何人都可以寫程式碼，但寫出好的註解很難。 大多數語言課程都以傳統的 Hello World 開始。即使在Oracle 教學的「入門」部分中，我們也從「Hello World!」開始。應用。從程式碼的第一行我們就看到了它們—Java 註解。在 Java 程式碼公約這樣重要的文件中，註釋被放在一個單獨的部分：註釋，這一事實也強調了它們的重要性。根據文檔，Java中的註釋分為兩種類型：

• 實現註釋（或代碼註釋）；
• 記錄評論。

程式碼註解用於描述單獨的行/區塊，文檔註解用於描述獨立於其實現的程式碼規格（其介面）。Java 註解會被編譯器忽略，因為 它們對開發人員有意義，但對使用者而言則不然。因此，您可以減少編譯類別的大小。

Java程式碼註解

從名稱中可以清楚地看出，該註釋與程式碼相關，並且應該反映其功能。程式碼註解為：

• 小寫（即在一行中描述）

  // Строчный комментарий
  System.out.println("Hello, World!");




• 塊（即它們被描述為一個完整的塊，因為它們不適合放在一行上）

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

區塊註解的一個有趣的功能是，如果我們以「 /*- 」 開頭（即在星號後面加上減號），則該區塊註解的文字將不會被格式化。很有趣，但藉助某些註釋，您可以提供一些 IDE 提示。例如，在 Eclipse IDE 中使用內嵌註解“ //@formatter:on ”和“ //@formatter:off ”，您可以停用程式碼片段的格式設定。您需要謹慎使用註釋，並且僅在必要時使用。例如，您可以閱讀有關此主題的文章：“不要在程式碼上寫註釋！” 。羅伯特馬丁 (Robert Martin)寫了一本很棒的書，名為《清潔代碼：創建、分析和重建》。它有一個單獨的章節“評論”。作為本章的題詞，引用了一句同樣精彩的引言：“不要評論糟糕的代碼——重寫它”，來自 Brian W. Kernighan 和 P. J. Plower。本章可以在Google 圖書上找到。大致意思可以用他的一句話來表達：

每次你發表評論時，你都會皺眉，感覺自己很失敗。”

顯然，沒有絕對的真理，有時評論是必要的。但總有選擇，需要與不必要的評論作鬥爭。本章也提到了不尋常的註釋，TODO：

// TODO: Добавить World
System.out.println("Hello, ");

它們的要點是可以在 IDE 中以特殊方式處理它們。例如，在 IDEA 中，它們收集在單獨的選項卡上，您可以在其中查看它們： 還有一個帶有註釋的小謎題：「http://google.com」行是方法內的有效行，因為 這裡的http其實是一個標籤，然後是一個註解。通常許多註釋可以從程式碼註釋變成文件註釋，我們稍後會討論。

文件註釋

文件註解描述了公共 API。 API是應用程式介面，即可供其他開發人員執行任何操作的類別和方法。簡而言之，這些註釋應該解釋為什麼創建這個或那個類別和套件以及這個或那個方法的作用。如果需要，您也可以描述類別欄位。這正是我們在 IDE 的工具提示中看到的內容，它以 JavaDoc 的形式呈現。例如： 如果我們進入這個方法，我們可以看到這段文字來自哪裡： 再次，請參閱 Java 程式碼約定：有關如何正確格式化 JavaDoc 的程式碼約定。它們有點類似於區塊註釋，但使用的是兩個星號，而不是一個星號（不是 Asterix）。上面給了一個 JavaDoc 範例。描述所有可能性是沒有意義的，因為 Oracle 官方文件中已經對此進行了描述。因此，我們在官方JavaDoc文件的「標籤描述」部分中查看我們需要的所有內容。Oracle 甚至有一個關於此主題的單獨教學：如何為 Javadoc 工具編寫文件註解。IDE 中的工具提示很不錯，但它們實際上是文件是有原因的。根據這些 JavaDoc 註釋，產生文件。有一個專門用於此目的的javadoc實用程式。正如我們所看到的，該教程討論了這一點。Oracle 官方網站上的JavaDoc有關如何使用它的說明。要親眼看看它是什麼樣子，您可以在目錄中使用套件的名稱建立子目錄，例如：test。建立一個簡單的類，其中包含註解。例如：

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

之後，我們可以從包含我們的套件目錄的目錄中執行以下命令： javadoc -d ./test test 之後，我們將看到文件產生過程。 然後我們可以打開index.html來查看生成的文檔。您經常會看到發布的 API 文件。例如，Spring 框架 API。

結論

我們可以看到，評論這樣看似簡單的事情其實要複雜得多。因此，如果您花一些時間在註釋上並遵循它們，您的程式碼將會更好，並且您作為程式設計師將更有價值。#維亞切斯拉夫