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。

结论

我们可以看到，评论这样看似简单的事情实际上要复杂得多。因此，如果您花一些时间在注释上并遵循它们，您的代码将会更好，并且您作为程序员将更有价值。#维亚切斯拉夫