Comments in Java: not so simple

Introduction

Comments - it would seem that it could be easier, and why write an entire article here. But it's not all that simple. As my boss used to say, anyone can write code, but it's hard to write a good commentary. Most language courses start with the traditional Hello World. Even in the 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 . As the documentation says, comments in Java are divided into two types:

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

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

Java code comments

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

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

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




• Block (that is, they are described by 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 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 hints to some IDEs. For example, using the line comments " //@formatter:on " and " //@formatter:off " in the Eclipse IDE, you can turn off formatting for sections of code. Use comments sparingly and only where necessary. For example, you can read an article on this topic: "Do not write comments on the code!" . There is an excellent book " Clean Code: Creation, Analysis and Refactoring".", which was written by Robert Martin. It has a separate chapter "Comments". As an epigraph to this chapter, there is an equally excellent quote: "Don't comment on 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 of his quotes:

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 excessive comments must be fought. The same chapter mentions unusual comments, TODO:

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

The point is that they can be handled in a special way by the IDE. For example, in IDEA they are collected on a separate tab where they can be viewed: And a small puzzler with a comment: The string "http://google.com" is a valid string inside the method, because http here is actually a label, and then a comment. Often, many comments can turn from code comments into documentation comments, which we'll talk about next.

Comments for documentation

Documentation comments describe the public API. An API is an 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. It is exactly what is formatted as a JavaDoc that we see in our IDE tooltips. For example: If we jump into this method, we can see where this text came from: We again look at how to format JavaDoc correctly in Java Code Convention: Code Convention . They are somewhat similar to block comments, but instead of one asterisk (not Asterix)) two are used. An example JavaDoc has been provided above. It makes no sense to describe all the possibilities, since this is already written in the official Oracle documentation. Therefore, we look at everything we 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 . Tips in the IDE are fine, but they're not really just doc. Documentation is generated based on these JavaDoc comments. There is a special javadoc utility for this.. As we can see, that Tutorial is about this. A description of how to use it is on the official Oracle website for JavaDoc . To see first hand what it looks like, you can create a subdirectory in the directory with the name of the package, for example: test . In it, create a simple class with comments. 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 that, we can execute the following command from the directory that contains our package directory: javadoc -d ./test test After that, we will see the documentation generation process. And then we can open index.html to see the generated document. You will often be able to see when API documentation is exposed. For example, the Spring Framework API .

Conclusion

As we can see, it would seem that such a simple thing as comments actually turns out to be much more complicated. Therefore, if comments are given some time and followed, your code will be better and you as a programmer will be more valuable. #Viacheslav