Comments in Java: not everything is so simple

Introduction

Comments - it would seem that it could be simpler, and why write a whole article. But it's not that simple. As my boss said, anyone can write code, but writing a good comment is difficult. Most language courses start with the traditional Hello World. Even in Oracle Tutorials, in the "Getting Started" section, we start with The "Hello World!" Application . And from the very first lines of code we see them - Java comments. Their importance is also emphasized by the fact that in such an important document as the Java Code Convention, comments are given a separate section: Comments . According to the documentation, comments in Java are divided into two types:

• implementation comment (or code comment);
• documenting comment.

Code comments are used to describe individual lines/blocks, and documentation comments are used to describe the specification of the code (its interface) independent of its implementation. Java comments are ignored by the compiler because they make sense to the developer, not the user. Therefore, you can reduce the size of compiled classes.

Java code comments

From the name it is clear that this comment relates to the code and should reflect its features. Code comments are:

• Lowercase (i.e. described in one line)

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




• Block (i.e. they are described as a whole block, because they do not fit on one line)

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

An interesting feature of a block comment is that if we start it with “ /*- ” (i.e. add a minus sign after the asterisk), then the text of this block comment will not be formatted. Interesting, but with the help of certain comments you can give some IDE hints. For example, using the inline comments " //@formatter:on " and " //@formatter:off " in the Eclipse IDE you can disable formatting for sections of code. You need to use comments sparingly and only where necessary. For example, you can read an article on this topic: “Don’t write comments on code!” . There is a great book called Clean Code: Creating, Analyzing, and Refactoring by Robert Martin. It has a separate chapter “Comments”. As an epigraph to this chapter, an equally excellent quote: “Don't comment bad code—rewrite it” from Brian W. Kernighan and P. J. Plower. This chapter can be found on Google Books . The general meaning can be expressed in one quote from him:

Every time you write a comment, wince and feel like a failure."

It is clear that there is no absolute truth, and sometimes comments are necessary. But there are always options, and unnecessary comments need to be fought. This chapter also mentions unusual comments, TODO:

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

The point of them is that they can be handled in a special way in the IDE. For example, in IDEA they are collected on a separate tab, where you can view them: And a small puzzler with a comment: The line “http://google.com” is a valid line inside the method, because http here is actually a tag, and then a comment. Often many comments can go from code comments to documentation comments, which we'll talk about later.

Comments for documentation

Documentation comments describe the public API. API is the application programming interface, that is, those classes and methods that are available to other developers to perform any actions. In short, these comments should explain why this or that class and package was created and what this or that method does. You can also describe class fields if necessary. This is exactly what we see in the tooltips of our IDEs, which is presented as a JavaDoc. For example: If we go into this method, we can see where this text comes from: Again, see the Java Code Convention: Code Convention on how to properly format a JavaDoc . They are somewhat similar to block comments, but instead of one asterisk (not Asterix)) two are used. An example JavaDoc was given above. There is no point in describing all the possibilities, since this is already written about in the official Oracle documentation. Therefore, we look at everything you need in the official JavaDoc documentation , section "Tag Descriptions". Oracle even has a separate tutorial on this topic: How to Write Doc Comments for the Javadoc Tool . Tooltips in the IDE are nice, but they're actually docs for a reason. Based on these JavaDoc comments, documentation is generated. There is a special javadoc utility for this . As we can see, that Tutorial talks about this. A description of how to use it is on the official Oracle website for JavaDoc . To see for yourself what this looks like, you can create a subdirectory in the directory with the name of the package, for example: test . Create a simple class with comments in it. For example:

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);
  }
}

After this, we can run the following command from the directory that contains our package directory: javadoc -d ./test test After this, we will see the documentation generation process. And then we can open index.html to see the generated document. You'll often see API documentation being posted. For example, Spring Framework API .

Conclusion

As we can see, such a seemingly simple thing as comments turns out to be much more complicated in reality. Therefore, if you spend some time on comments and follow them, your code will be better and you will be more valuable as a programmer. #Viacheslav